# STARTHERE — mgf-livepush

> **Sibling library in the Magogi Foundation federation.**
> See [README.md](README.md) for what this library does; see
> [PUBLIC_API.md](PUBLIC_API.md) for the surface; see
> [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md)
> for the federation contract.

`mgf-livepush` is a realtime push pipeline for `mgf-common` consumers:
an SSE streaming primitive, a pluggable pub/sub broker seam (Redis +
in-process mock), and a per-key connection-slot cap.

---

## For consumers (using this library)

1. **Pin** in your `pyproject.toml`:
   ```toml
   dependencies = ["mgf-livepush>=X.Y,<X.$((Y+1))"]
   ```
   See [CHANGELOG.md](CHANGELOG.md) for the current minor.
2. **Install:** `uv add "mgf-livepush[redis,fastapi]"` (or
   `pip install "mgf-livepush[redis,fastapi]"`). Adapters are opt-in
   extras — `[redis]` for `RedisBroker`, `[fastapi]` for the
   `sse_streaming_response` wrapper.
3. **First run (FastAPI):**
   ```python
   from redis.asyncio import Redis
   from mgf.livepush import SSEStreamService, RedisBroker, SlotCap
   from mgf.livepush.fastapi import sse_streaming_response

   redis = Redis.from_url("redis://localhost:6379/0")
   sse = SSEStreamService(RedisBroker(redis), SlotCap(redis, cap=20))

   @router.get("/events/stream")
   async def stream(request: Request):
       return await sse_streaming_response(
           sse, request, channel=f"events:{tenant_id}", slot_key=str(tenant_id)
       )
   ```
   Tests can use `MockBroker` (no Redis). The framework-agnostic core
   (`open_stream(...)` → `SSEStream`) works without the `[fastapi]` extra.
4. **Read** [PUBLIC_API.md](PUBLIC_API.md) for the stable surface
   (`SSEStreamService` / `Broker` / `RedisBroker` / `MockBroker` /
   `SlotCap`). Note the dev/prod-proxy SSE recipe in the README — it is
   the buffering tarpit.
5. **Bootstrap your app** with mgf-common first — see
   [mgf-common/STARTHERE.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md).
6. **Adopt the federation contract** — file your
   `MGF_STANDARDS_CONFORMANCE.md` per
   [DOC-15](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md).
7. **Run** `mgf-common catch-up` periodically to verify
   federation drift; see [FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) §6.

---

## For contributors

See [CONTRIBUTING.md](CONTRIBUTING.md). Standards are inherited
from [mgf-common](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).

---

## Quick links

| Resource | Where |
|---|---|
| Library purpose | [README.md](README.md) |
| Stable surface | [PUBLIC_API.md](PUBLIC_API.md) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) |
| Dependencies + who depends on me | [DEPS.md](DEPS.md) |
| Conformance ledger | [docs/inprogress/MGF_STANDARDS_CONFORMANCE.md](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md) |
| Federation contract | [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) |
| Cross-project standards | [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) |
