tempest-fastapi-sdk 0.81.2__tar.gz → 0.82.0__tar.gz

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.82.0] — 2026-06-28
+
+### Added
+
+- **`SSEBroker` — multi-worker SSE fan-out.** The SSE recipe described a
+  Redis Pub/Sub bridge for broadcasting across workers but shipped no
+  primitive; `SSEBroker` is that primitive. It keeps a per-channel
+  registry of local `EventStream`s and fans `publish(channel, ...)` out
+  to them. Pass a `[cache]` Redis client and the same broker publishes
+  via Redis `PUBLISH` while a background `run()` task `PSUBSCRIBE`-s the
+  channel prefix and relays every message to each worker's local
+  streams — so `publish` becomes cross-process with no call-site change
+  (`register` / `unregister` / `publish` are identical in both modes).
+  Exported from `tempest_fastapi_sdk` and `tempest_fastapi_sdk.sse`. The
+  SSE recipe now shows the in-memory and Redis-lifespan setups.
+
 ## [0.81.2] — 2026-06-28
 
 ### Changed

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.81.2
+Version: 0.82.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -250,7 +250,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum`, `strict_types`/`typed`/`require_annotations` |
 | `tempest_fastapi_sdk.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel`, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
-| `tempest_fastapi_sdk.sse` | `EventStream`, `ServerSentEvent`, `sse_response` |
+| `tempest_fastapi_sdk.sse` | `EventStream`, `SSEBroker` (multi-worker fan-out via Redis), `ServerSentEvent`, `sse_response` |
 | `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
 | `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/README.md

@@ -147,7 +147,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum`, `strict_types`/`typed`/`require_annotations` |
 | `tempest_fastapi_sdk.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel`, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
-| `tempest_fastapi_sdk.sse` | `EventStream`, `ServerSentEvent`, `sse_response` |
+| `tempest_fastapi_sdk.sse` | `EventStream`, `SSEBroker` (multi-worker fan-out via Redis), `ServerSentEvent`, `sse_response` |
 | `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
 | `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/docs/recipes/sse.en.md

@@ -93,77 +93,96 @@ stream is idle so load-balancers don't cut the connection. Comments are
 **invisible** to `EventSource` — they fire no listener, they just keep
 the socket alive. `None` disables the heartbeat.
 
-## Broadcast to many clients
+## Broadcast to many clients (`SSEBroker`)
 
-`EventStream` is one connection. To send the same event to everyone (or
-to a user's devices), keep a registry of streams and publish to all — a
-simple "hub":
+`EventStream` is **one** connection. To send the same event to every
+client of a channel (e.g. a user's devices, or a topic), the SDK ships
+`SSEBroker` — a per-channel stream registry plus fan-out. The channel is
+any string (a user id, a room slug...).
 
 ```python
-# src/services/sse_hub.py
-from uuid import UUID
-
-from tempest_fastapi_sdk import EventStream
+# src/api/dependencies/resources.py
+from tempest_fastapi_sdk import SSEBroker
 
+broker = SSEBroker()   # singleton — keep on app.state and inject via Depends
+```
 
-class SSEHub:
-    """In-memory registry of open SSE streams, per user."""
+```python
+# src/api/routers/feed.py
+from uuid import UUID
 
-    def __init__(self) -> None:
-        self._streams: dict[UUID, set[EventStream]] = {}
+from fastapi import APIRouter, Depends
+from starlette.responses import StreamingResponse
 
-    def register(self, user_id: UUID) -> EventStream:
-        """Open a stream for a client and register it."""
-        stream = EventStream(heartbeat_seconds=15.0)
-        self._streams.setdefault(user_id, set()).add(stream)
-        return stream
+from tempest_fastapi_sdk import sse_response
 
-    def unregister(self, user_id: UUID, stream: EventStream) -> None:
-        """Drop a closed stream from the registry."""
-        streams = self._streams.get(user_id)
-        if streams:
-            streams.discard(stream)
-            if not streams:
-                del self._streams[user_id]
+router = APIRouter()
 
-    async def publish_to_user(self, user_id: UUID, data: object, *, event: str) -> int:
-        """Publish an event to all of a user's open streams."""
-        streams = self._streams.get(user_id, set())
-        for stream in streams:
-            await stream.publish(data, event=event)
-        return len(streams)
-```
 
-```python
-# src/api/routers/feed.py
 @router.get("/feed")
 async def feed(
     user_id: UUID = Depends(get_current_user_id),
-    hub: SSEHub = Depends(get_sse_hub),       # singleton on app.state
+    broker: SSEBroker = Depends(get_broker),
 ) -> StreamingResponse:
-    """Subscribe the client to its user's feed."""
-    stream = hub.register(user_id)
+    """Subscribe the client to its user's channel."""
+    channel = str(user_id)
+    stream = broker.register(channel)
 
     async def lifecycle_aware() -> AsyncIterator[bytes]:
         try:
             async for chunk in stream.stream():
                 yield chunk
         finally:
-            hub.unregister(user_id, stream)
+            broker.unregister(channel, stream)   # client left
 
     return sse_response(lifecycle_aware())
 
 
 # From anywhere (queue handler, another endpoint):
-# await hub.publish_to_user(user_id, {"text": "New order"}, event="notice")
+# await broker.publish(str(user_id), {"text": "New order"}, event="notice")
+```
+
+### Multi-worker: Redis bridge (ready, no extra code)
+
+An in-memory `SSEBroker` lives in **one** worker — with `--workers N` a
+`publish` only reaches the clients pinned to that process. Pass a Redis
+client and the **same `broker`** publishes via Redis `PUBLISH`; a
+background task (`run()`) `PSUBSCRIBE`-s and relays to **each** worker's
+local streams. Same call site, now horizontal:
+
+```python
+# src/api/app.py
+import asyncio
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from redis.asyncio import Redis
+
+from tempest_fastapi_sdk import SSEBroker
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+broker = SSEBroker(redis=redis, channel_prefix="sse")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    task = asyncio.create_task(broker.run())   # subscribe Redis + fan out
+    try:
+        yield
+    finally:
+        await broker.aclose()
+        task.cancel()
+
+
+app = FastAPI(lifespan=lifespan)
+# broker.publish(...) on any worker -> reaches ALL workers
 ```
 
-!!! danger "In-memory hub = single process"
-    The `SSEHub` above lives in **one** worker's memory. With multiple
-    workers (Gunicorn/Uvicorn `--workers N`), a publish only reaches the
-    clients pinned to that process. For multi-process, back the hub with a
-    Pub/Sub (Redis `PUBLISH`/`SUBSCRIBE`): each worker subscribes to the
-    channel and relays to its local streams.
+!!! tip "Start simple, scale later"
+    Without Redis, `SSEBroker()` already covers a single process. When you
+    need multiple workers/hosts, just inject a Redis client and start
+    `run()` in the lifespan — no endpoint changes. `publish` becomes
+    cross-process for free.
 
 ## Aligned with tempest-react-sdk
 
@@ -202,5 +221,5 @@ Alignment points:
 - Tie the producer to the connection lifecycle (`finally` → cancel/unregister).
 - `publish(data, event=, id=, retry=)` covers the 4 spec fields; non-string `data` becomes JSON.
 - Heartbeat is a comment (invisible to EventSource); `None` disables it.
-- Broadcast = a registry of streams (hub); multi-worker needs Pub/Sub (Redis).
+- Broadcast = `SSEBroker` (per-channel stream registry); multi-worker = pass a Redis client + start `broker.run()` in the lifespan (same call site).
 - `tempest-react-sdk` `createEventStream`/`useEventStream` consumes with reconnect; `namedEvents` ↔ `publish(event=)`.

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/docs/recipes/sse.md

@@ -93,77 +93,96 @@ stream fica ocioso, pra load-balancers não cortarem a conexão.
 Comentários são **invisíveis** ao `EventSource` — não disparam nenhum
 listener, só mantêm o socket vivo. `None` desliga o heartbeat.
 
-## Broadcast pra vários clientes
+## Broadcast pra vários clientes (`SSEBroker`)
 
-`EventStream` é uma conexão. Pra mandar o mesmo evento pra todos (ou pros
-devices de um usuário), mantenha um registro de streams e publique em
-todos — um "hub" simples:
+`EventStream` é **uma** conexão. Pra mandar o mesmo evento pra todos os
+clientes de um canal (ex.: os devices de um usuário, ou um tópico), o SDK
+traz o `SSEBroker` — registro de streams por canal + fan-out. O canal é
+uma string qualquer (id de usuário, slug de sala...).
 
 ```python
-# src/services/sse_hub.py
-from uuid import UUID
-
-from tempest_fastapi_sdk import EventStream
+# src/api/dependencies/resources.py
+from tempest_fastapi_sdk import SSEBroker
 
+broker = SSEBroker()   # singleton — guarde em app.state e injete via Depends
+```
 
-class SSEHub:
-    """Registro em memória de streams SSE abertos, por usuário."""
+```python
+# src/api/routers/feed.py
+from uuid import UUID
 
-    def __init__(self) -> None:
-        self._streams: dict[UUID, set[EventStream]] = {}
+from fastapi import APIRouter, Depends
+from starlette.responses import StreamingResponse
 
-    def register(self, user_id: UUID) -> EventStream:
-        """Abre um stream para um cliente e o registra."""
-        stream = EventStream(heartbeat_seconds=15.0)
-        self._streams.setdefault(user_id, set()).add(stream)
-        return stream
+from tempest_fastapi_sdk import sse_response
 
-    def unregister(self, user_id: UUID, stream: EventStream) -> None:
-        """Remove um stream fechado do registro."""
-        streams = self._streams.get(user_id)
-        if streams:
-            streams.discard(stream)
-            if not streams:
-                del self._streams[user_id]
+router = APIRouter()
 
-    async def publish_to_user(self, user_id: UUID, data: object, *, event: str) -> int:
-        """Publica um evento em todos os streams abertos de um usuário."""
-        streams = self._streams.get(user_id, set())
-        for stream in streams:
-            await stream.publish(data, event=event)
-        return len(streams)
-```
 
-```python
-# src/api/routers/feed.py
 @router.get("/feed")
 async def feed(
     user_id: UUID = Depends(get_current_user_id),
-    hub: SSEHub = Depends(get_sse_hub),       # singleton no app.state
+    broker: SSEBroker = Depends(get_broker),
 ) -> StreamingResponse:
-    """Inscreve o cliente no feed do seu usuário."""
-    stream = hub.register(user_id)
+    """Inscreve o cliente no canal do seu usuário."""
+    channel = str(user_id)
+    stream = broker.register(channel)
 
     async def lifecycle_aware() -> AsyncIterator[bytes]:
         try:
             async for chunk in stream.stream():
                 yield chunk
         finally:
-            hub.unregister(user_id, stream)
+            broker.unregister(channel, stream)   # cliente saiu
 
     return sse_response(lifecycle_aware())
 
 
 # De qualquer lugar (handler de fila, outro endpoint):
-# await hub.publish_to_user(user_id, {"text": "Novo pedido"}, event="notice")
+# await broker.publish(str(user_id), {"text": "Novo pedido"}, event="notice")
+```
+
+### Multi-worker: bridge Redis (pronto, sem código extra)
+
+O `SSEBroker` em memória vive em **um** worker — com `--workers N`, um
+`publish` só alcança os clientes presos naquele processo. Passe um client
+Redis e o **mesmo `broker`** passa a publicar via Redis `PUBLISH`; uma
+task de fundo (`run()`) faz `PSUBSCRIBE` e repassa pros streams locais de
+**cada** worker. Mesmo call site, agora horizontal:
+
+```python
+# src/api/app.py
+import asyncio
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from redis.asyncio import Redis
+
+from tempest_fastapi_sdk import SSEBroker
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=True)
+broker = SSEBroker(redis=redis, channel_prefix="sse")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    task = asyncio.create_task(broker.run())   # assina o Redis e faz o fan-out
+    try:
+        yield
+    finally:
+        await broker.aclose()
+        task.cancel()
+
+
+app = FastAPI(lifespan=lifespan)
+# broker.publish(...) em qualquer worker -> chega em TODOS os workers
 ```
 
-!!! danger "Hub em memória = um processo só"
-    O `SSEHub` acima vive na memória de **um** worker. Com vários workers
-    (Gunicorn/Uvicorn `--workers N`), um publish só alcança os clientes
-    presos naquele processo. Pra multi-processo, ligue o hub a um
-    Pub/Sub (Redis `PUBLISH`/`SUBSCRIBE`): cada worker assina o canal e
-    repassa pros seus streams locais.
+!!! tip "Comece simples, escale depois"
+    Sem Redis, `SSEBroker()` já resolve um processo. Quando precisar de
+    múltiplos workers/hosts, só injete o client Redis e suba o `run()` no
+    lifespan — nenhum endpoint muda. O `publish` se torna cross-process de
+    graça.
 
 ## Alinhado com o tempest-react-sdk
 
@@ -202,5 +221,5 @@ Pontos de alinhamento:
 - Amarre o produtor ao ciclo de vida da conexão (`finally` → cancela/desregistra).
 - `publish(data, event=, id=, retry=)` cobre os 4 campos do spec; `data` não-string vira JSON.
 - Heartbeat é comentário (invisível ao EventSource); `None` desliga.
-- Broadcast = registro de streams (hub); multi-worker exige Pub/Sub (Redis).
+- Broadcast = `SSEBroker` (registro de streams por canal); multi-worker = passe um client Redis + suba `broker.run()` no lifespan (mesmo call site).
 - `tempest-react-sdk` `createEventStream`/`useEventStream` consome com reconnect; `namedEvents` ↔ `publish(event=)`.

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/docs/reference.md

@@ -241,6 +241,7 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ### `tempest_fastapi_sdk.sse`
 
 ::: tempest_fastapi_sdk.sse.event_stream.EventStream
+::: tempest_fastapi_sdk.sse.broker.SSEBroker
 ::: tempest_fastapi_sdk.sse.event_stream.ServerSentEvent
 ::: tempest_fastapi_sdk.sse.event_stream.sse_response
 

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.81.2"
+version = "0.82.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/tempest_fastapi_sdk/__init__.py

@@ -233,7 +233,12 @@ from tempest_fastapi_sdk.settings import (
     WebPushSettings,
     WebSocketSettings,
 )
-from tempest_fastapi_sdk.sse import EventStream, ServerSentEvent, sse_response
+from tempest_fastapi_sdk.sse import (
+    EventStream,
+    ServerSentEvent,
+    SSEBroker,
+    sse_response,
+)
 from tempest_fastapi_sdk.storage import AsyncMinIOClient, ObjectStat
 from tempest_fastapi_sdk.utils import (
     CEP,
@@ -346,7 +351,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.81.2"
+__version__: str = "0.82.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -517,6 +522,7 @@ __all__: list[str] = [
     "Region",
     "RequestIDMiddleware",
     "RetryPolicy",
+    "SSEBroker",
     "SameSite",
     "ServerSentEvent",
     "ServerSettings",

{tempest_fastapi_sdk-0.81.2 → tempest_fastapi_sdk-0.82.0}/tempest_fastapi_sdk/sse/__init__.py

@@ -1,5 +1,6 @@
 """Server-Sent Events helpers built on top of Starlette streaming."""
 
+from tempest_fastapi_sdk.sse.broker import SSEBroker
 from tempest_fastapi_sdk.sse.event_stream import (
     EventStream,
     ServerSentEvent,
@@ -8,6 +9,7 @@ from tempest_fastapi_sdk.sse.event_stream import (
 
 __all__: list[str] = [
     "EventStream",
+    "SSEBroker",
     "ServerSentEvent",
     "sse_response",
 ]

tempest_fastapi_sdk-0.82.0/tempest_fastapi_sdk/sse/broker.py

@@ -0,0 +1,208 @@
+"""Multi-worker SSE fan-out: local registry + optional Redis pub/sub bridge.
+
+:class:`EventStream` feeds **one** connection. To broadcast the same
+event to every client subscribed to a channel — across multiple
+Uvicorn/Gunicorn workers — you need a fan-out layer plus a cross-process
+transport. :class:`SSEBroker` is both:
+
+* **Single process** (``redis=None``) — keeps a registry of local
+  streams per channel; :meth:`publish` fans out to them in-process.
+* **Multi-worker** (``redis=<client>``) — :meth:`publish` goes through
+  Redis ``PUBLISH``; a background :meth:`run` task ``PSUBSCRIBE``-s the
+  channel prefix and re-fans every message to the worker's local
+  streams. Run :meth:`run` from the app lifespan and stop it with
+  :meth:`aclose`.
+
+The same call site (``register`` / ``publish`` / ``unregister``) works in
+both modes, so a service starts single-process and gains horizontal
+scale by passing a Redis client — no code change.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from tempest_fastapi_sdk.sse.event_stream import EventStream, ServerSentEvent
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+
+class SSEBroker:
+    """Channel-based SSE fan-out, optionally bridged over Redis pub/sub.
+
+    Attributes:
+        channel_prefix (str): Redis key prefix for published channels
+            (``"<prefix>:<channel>"``). Also the ``PSUBSCRIBE`` pattern
+            root. Ignored in single-process mode.
+        heartbeat_seconds (float | None): Idle interval passed to every
+            :class:`EventStream` created by :meth:`register`.
+    """
+
+    def __init__(
+        self,
+        *,
+        redis: Redis | None = None,
+        channel_prefix: str = "sse",
+        heartbeat_seconds: float | None = 15.0,
+    ) -> None:
+        """Initialize the broker.
+
+        Args:
+            redis (Redis | None): Async Redis client (from the ``[cache]``
+                extra). ``None`` runs single-process (local fan-out only).
+            channel_prefix (str): Prefix for Redis channels.
+            heartbeat_seconds (float | None): Idle heartbeat for streams.
+        """
+        self._redis: Redis | None = redis
+        self.channel_prefix: str = channel_prefix
+        self.heartbeat_seconds: float | None = heartbeat_seconds
+        self._channels: dict[str, set[EventStream]] = {}
+        self._pubsub: Any = None
+
+    def register(self, channel: str) -> EventStream:
+        """Open a local stream subscribed to ``channel`` and track it.
+
+        Args:
+            channel (str): The logical channel (e.g. a user id or topic).
+
+        Returns:
+            EventStream: A fresh stream to hand to
+            :func:`tempest_fastapi_sdk.sse_response`.
+        """
+        stream = EventStream(heartbeat_seconds=self.heartbeat_seconds)
+        self._channels.setdefault(channel, set()).add(stream)
+        return stream
+
+    def unregister(self, channel: str, stream: EventStream) -> None:
+        """Drop a closed stream from ``channel``.
+
+        Call this from the response generator's ``finally`` so a
+        disconnected client is forgotten.
+
+        Args:
+            channel (str): The channel the stream was registered under.
+            stream (EventStream): The stream to remove.
+        """
+        streams = self._channels.get(channel)
+        if streams:
+            streams.discard(stream)
+            if not streams:
+                del self._channels[channel]
+
+    def local_subscribers(self, channel: str) -> int:
+        """Return how many local streams are open on ``channel``.
+
+        Args:
+            channel (str): The channel to inspect.
+
+        Returns:
+            int: The local subscriber count (this worker only).
+        """
+        return len(self._channels.get(channel, set()))
+
+    async def publish(
+        self,
+        channel: str,
+        data: Any = "",
+        *,
+        event: str | None = None,
+        id: str | None = None,
+        retry: int | None = None,
+    ) -> None:
+        """Publish an event to every subscriber of ``channel``.
+
+        In Redis mode the event is ``PUBLISH``-ed and delivered to all
+        workers (including this one) by their :meth:`run` loop. In
+        single-process mode it fans out to local streams immediately.
+
+        Args:
+            channel (str): Target channel.
+            data (Any): Payload (string, bytes or JSON-serializable).
+            event (str | None): Optional SSE event name.
+            id (str | None): Optional ``Last-Event-ID``.
+            retry (int | None): Optional reconnect hint (ms).
+        """
+        if self._redis is None:
+            await self._emit_local(
+                channel,
+                ServerSentEvent(data=data, event=event, id=id, retry=retry),
+            )
+            return
+        envelope = json.dumps(
+            {"data": data, "event": event, "id": id, "retry": retry},
+            default=str,
+        )
+        await self._redis.publish(self._key(channel), envelope)
+
+    async def run(self) -> None:
+        """Consume Redis pub/sub and fan messages to local streams.
+
+        Long-running: start it as a background task in the app lifespan
+        and cancel it (or call :meth:`aclose`) on shutdown. A no-op in
+        single-process mode.
+
+        Raises:
+            RuntimeError: If called without a Redis client.
+        """
+        if self._redis is None:
+            raise RuntimeError("SSEBroker.run() requires a Redis client.")
+        pubsub: Any = self._redis.pubsub()
+        self._pubsub = pubsub
+        await pubsub.psubscribe(f"{self.channel_prefix}:*")
+        try:
+            async for message in pubsub.listen():
+                if message.get("type") != "pmessage":
+                    continue
+                await self._dispatch_raw(message["channel"], message["data"])
+        finally:
+            await pubsub.aclose()
+            self._pubsub = None
+
+    async def aclose(self) -> None:
+        """Stop the pub/sub subscription opened by :meth:`run`."""
+        if self._pubsub is not None:
+            await self._pubsub.aclose()
+            self._pubsub = None
+
+    def _key(self, channel: str) -> str:
+        """Return the Redis channel key for ``channel``."""
+        return f"{self.channel_prefix}:{channel}"
+
+    async def _dispatch_raw(self, channel_key: str | bytes, raw: str | bytes) -> None:
+        """Decode a Redis pub/sub frame and fan it to local streams.
+
+        Args:
+            channel_key (str | bytes): The Redis channel
+                (``<prefix>:<channel>``), as delivered by pub/sub.
+            raw (str | bytes): The JSON envelope payload.
+        """
+        key = channel_key.decode() if isinstance(channel_key, bytes) else channel_key
+        body = raw.decode() if isinstance(raw, bytes) else raw
+        channel = key.removeprefix(f"{self.channel_prefix}:")
+        payload: dict[str, Any] = json.loads(body)
+        await self._emit_local(
+            channel,
+            ServerSentEvent(
+                data=payload.get("data", ""),
+                event=payload.get("event"),
+                id=payload.get("id"),
+                retry=payload.get("retry"),
+            ),
+        )
+
+    async def _emit_local(self, channel: str, event: ServerSentEvent) -> None:
+        """Enqueue ``event`` on every local stream of ``channel``.
+
+        Args:
+            channel (str): The channel to fan out to.
+            event (ServerSentEvent): The event to deliver.
+        """
+        for stream in tuple(self._channels.get(channel, set())):
+            await stream.publish_event(event)
+
+
+__all__: list[str] = [
+    "SSEBroker",
+]