# sse-handler

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Hono handler factory that turns a subscription on `SseService` into a streaming HTTP response framed in the `text/event-stream` wire format. Handles per-connection heartbeats, abort-on-disconnect via the request's `AbortSignal`, `Last-Event-ID` resume from the ring buffer, and backpressure honoring the configured `queueHighWaterMark` and `overflowPolicy`. Returns a standard `Response` whose body is a `ReadableStream<Uint8Array>` so any modern runtime (Bun, Node 18+, Cloudflare Workers, Deno) streams without an adapter shim.

## Features

- Reads `:channel` from the route path; missing throws `SseError(SSE_CHANNEL_REQUIRED)` for the host's error handler to translate to 400.
- Reads `Last-Event-ID` from request headers and forwards to `service.subscribe` for replay.
- Optional `resolvePrincipalId(c)` lets consumers wire any auth stack (e.g. `c.get("user")?.id`) without this package depending on `@suaveplan/api-plugin-auth`.
- Optional `requirePrincipal: true` raises `SseError(SSE_UNAUTHENTICATED)` (HTTP 401) when the resolver returns `undefined`.
- Heartbeat scheduler writes a `: heartbeat\n\n` comment frame every `heartbeatIntervalMs` to keep idle connections alive through proxies; the timer is injectable (`setIntervalImpl`/`clearIntervalImpl`) for deterministic tests.
- Backpressure handling: when the writable controller's `desiredSize` falls to zero or the in-memory backlog exceeds `queueHighWaterMark`, applies `overflowPolicy` and increments `sse.queue_overflow_total{policy, code}`.
- Sets canonical response headers: `Content-Type: text/event-stream; charset=utf-8`, `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no`, `Connection: keep-alive`.

## Usage: Basic

```ts
import { Hono } from "hono";
import { createSseRoute } from "@suaveplan/api-plugin-sse/middleware/sse-handler";

const app = new Hono();
app.get(
    "/sse/:channel",
    createSseRoute(sseService, {
        heartbeatIntervalMs: 30_000,
        queueHighWaterMark: 256,
        overflowPolicy: "drop-oldest",
    })
);
```

## Usage: Advanced

```ts
import { Hono } from "hono";
import { createSseRoute } from "@suaveplan/api-plugin-sse/middleware/sse-handler";
import { requireAuth } from "@suaveplan/api-plugin-auth/middleware/require-auth";

const app = new Hono();

// Compose with the auth plugin: require an authenticated principal,
// scope the principalId to the subscription cap.
app.get(
    "/sse/:channel",
    requireAuth(),
    createSseRoute(sseService, {
        heartbeatIntervalMs: 15_000,
        queueHighWaterMark: 128,
        overflowPolicy: "drop-newest",
        resolvePrincipalId: (c) => c.get("user")?.id,
        requirePrincipal: true,
    })
);
```

## API Reference

- `interface CreateSseRouteOptions` — `{ heartbeatIntervalMs, queueHighWaterMark, overflowPolicy, resolvePrincipalId?, requirePrincipal?, setIntervalImpl?, clearIntervalImpl? }`.
- `createSseRoute(service: SseService, options: CreateSseRouteOptions): Handler` — returns a Hono handler.

## Implementation Notes

- The response body is constructed as `new ReadableStream<Uint8Array>` with an async producer running inside `start(controller)`. The producer drains `handle.events` via `for await`, frames each event with `formatSseFrame`, and pushes the encoded bytes through the controller.
- Cleanup is centralised in a single async closure that clears the heartbeat interval, calls `handle.close()`, and records the `sse.connection_duration_ms` histogram. It is invoked from both the iterator's `finally` branch and the stream's `cancel` callback so abort and natural end converge on the same code path.
- Backpressure is detected by checking `controller.desiredSize`; values of `null` (no high-water mark) and positive integers are treated as "not full". Zero or negative trigger the overflow policy.
- Heartbeat interval uses native `setInterval` by default; tests inject a fake to drive the timer deterministically (matching the FakeClock pattern used elsewhere ).