# Public API — `mgf-livepush`

> **Master-HEAD banner:** tracks the public surface of the CURRENT main/release.
> Verify your pinned version via `mgf.livepush.__version__` (mirrors
> `pyproject.toml::project.version`). Machine-readable companion:
> [`PUBLIC_API.json`](PUBLIC_API.json), generated from `__all__` + pinned in CI.

The public surface is exactly `mgf.livepush.__all__`. Modules under a leading
underscore (`_broker`, `_sse`, `_slotcap`, `_errors`) are private.

- **Stability tiers:** `experimental` (MAY change in any MINOR — the 0.x window),
  `stable` (deprecation cycle; removal only in MAJOR), `deprecated`.

## `mgf.livepush`

| Name | Tier | Description |
|---|---|---|
| `SSEStreamService` | experimental | Orchestrates an SSE stream over a `Broker` + `SlotCap`; `open_stream(...)` yields events until disconnect. |
| `SSEStream` | experimental | Transport container (headers + async event iterator) returned by the service. |
| `sse_headers` | experimental | The canonical SSE response headers (no-cache, text/event-stream, keep-alive). |
| `Broker` | experimental | Protocol: the pub/sub seam (`publish` / `subscribe` → `Subscription`). |
| `Subscription` | experimental | Protocol: an open subscription (async iterator of messages + `aclose`). |
| `RedisBroker` | experimental | Production `Broker` over Redis pub/sub (optional `[redis]` extra). |
| `MockBroker` | experimental | In-process `Broker` for consumer tests. |
| `SlotCap` | experimental | Per-key connection-slot cap (backpressure / DoS bound; fail-open). |
| `LivePushError` | experimental | Base typed error (subclasses `mgf.common AppError`). |
| `CapExceededError` | experimental | Raised when a slot key is at capacity; `.slot_key` / `.cap` fields. |

## The FastAPI adapter

`sse_streaming_response` lives in `mgf.livepush.fastapi` — imported explicitly by
consumers using FastAPI (optional `[fastapi]` extra). It is NOT in the generic
`__all__`, so `import mgf.livepush` stays framework-free (the import-linter contract).
