pg-sse 0.1.0__py3-none-any.whl

pg_sse/__init__.py

@@ -0,0 +1,20 @@
+"""Live updates from the Postgres you already run, as server-sent events."""
+
+from ._event import Event
+from ._hub import CLOSING, DROPPED, RESYNC, Hub, HubStats, Subscription, TooManySubscribers, Wake
+from ._sql import drop_trigger_sql, trigger_sql
+
+__all__ = [
+    "CLOSING",
+    "DROPPED",
+    "RESYNC",
+    "Event",
+    "Hub",
+    "HubStats",
+    "Subscription",
+    "TooManySubscribers",
+    "Wake",
+    "drop_trigger_sql",
+    "trigger_sql",
+]
+__version__ = "0.1.0"

pg_sse/_event.py

@@ -0,0 +1,65 @@
+import json
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+# The only line endings the SSE parser knows; str.splitlines would also split on U+2028 and friends.
+_LINE_BREAK = re.compile(r"\r\n|\r|\n")
+_FORBIDDEN_IN_FIELD = re.compile(r"[\r\n\x00]")
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """
+    One server-sent event.
+
+    - `data`: a str is sent as is; anything else is sent as JSON.
+    - `id`: the cursor after this event. It is sent as the SSE id (so a browser reconnects with it as Last-Event-ID)
+      and handed back to your `read` as the cursor, unchanged.
+    - `event`: the SSE event name; None means the browser's default, "message".
+    - `final`: end the stream after this event, e.g. when the conversation it follows is closed.
+    """
+
+    data: Any
+    id: Any = None
+    event: str | None = None
+    final: bool = False
+
+
+def encode(event: Event, default: Callable[[Any], Any] | None = None) -> str:
+    """`default` is `json.dumps`'s: what to do with data that is not JSON-native (e.g. `str` for a datetime)."""
+    lines = []
+    if event.id is not None:
+        lines.append(f"id: {_field('id', str(event.id))}")
+    if event.event is not None:
+        lines.append(f"event: {_field('event', event.event)}")
+    data = event.data if isinstance(event.data, str) else json.dumps(event.data, separators=(",", ":"), default=default)
+    lines.extend(f"data: {line}" for line in _LINE_BREAK.split(data))
+    return "\n".join(lines) + "\n\n"
+
+
+def encode_cursor(cursor: Any) -> str:
+    """An id with no data: the browser records it as its Last-Event-ID and dispatches nothing."""
+    return f"id: {_field('id', str(cursor))}\n\n"
+
+
+def encode_goodbye(event_name: str | None, reason: str, retry_ms: int) -> str:
+    """
+    The last frame before a planned close. `retry:` sets the client's reconnect delay and dispatches nothing by
+    itself; the named event, with the reason as data, is sent only when asked for. No `id:`, so the client's
+    Last-Event-ID stays at the last real event.
+    """
+    lines = [f"retry: {retry_ms}"]
+    if event_name is not None:
+        lines += [
+            f"event: {_field('event', event_name)}",
+            f"data: {json.dumps({'reason': reason}, separators=(',', ':'))}",
+        ]
+    return "\n".join(lines) + "\n\n"
+
+
+def _field(name: str, value: str) -> str:
+    if _FORBIDDEN_IN_FIELD.search(value):
+        raise ValueError(f"an SSE {name} cannot contain a line break or NUL: {value!r}")
+    return value

pg_sse/_hub.py

@@ -0,0 +1,621 @@
+"""
+The hub: one LISTEN connection per process, fanned out to every open stream.
+
+A notification carries only a key and means "re-read from your cursor"; it never carries the data. So a lost
+notification costs a delay, never an event:
+
+- every stream subscribes before its catch-up read, so a write between the two is a queued wake-up, not a gap;
+- after the listener connects or reconnects, every stream re-reads (anything committed before its LISTEN existed
+  was missed);
+- every stream re-reads when nothing woke it for a while anyway.
+
+The listener is a thread holding one autocommit connection; each notification is handed to the event loop, where
+each stream has a bounded queue. A full queue ends that stream instead of blocking or growing: the browser reconnects
+with Last-Event-ID and catches up from the database.
+"""
+
+import asyncio
+import contextlib
+import inspect
+import logging
+import random
+import signal
+import threading
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Mapping
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from types import FrameType
+from typing import TYPE_CHECKING, Any, NoReturn
+
+import psycopg
+from psycopg import sql
+from psycopg.conninfo import conninfo_to_dict, make_conninfo
+
+from ._event import Event, encode, encode_cursor, encode_goodbye
+
+if TYPE_CHECKING:
+    from starlette.responses import StreamingResponse
+
+logger = logging.getLogger("pg_sse")
+
+# A queue holds ("notify", key) for a NOTIFY, ("wake", key, signal) for a `hub.wake`, or ("marker", m) with one of:
+RESYNC = "\x00resync"
+DROPPED = "\x00dropped"
+CLOSING = "\x00closing"
+QueueItem = tuple[str, ...]
+
+# The listener runs a trivial query this often, so a half-open connection (no FIN, no notifications) is noticed and
+# replaced; TCP keepalives bound how long that query can hang.
+_KEEPALIVE_QUERY_SECONDS = 60.0
+_TCP_KEEPALIVES = {"keepalives": 1, "keepalives_idle": 30, "keepalives_interval": 10, "keepalives_count": 3}
+# A connect that hangs (a black-holed host) must not pin the listener thread; a DSN's own connect_timeout wins.
+_CONNECT_TIMEOUT_SECONDS = 10
+# The listener runs nothing but LISTEN and SELECT 1, so a query that takes this long is stuck.
+_STATEMENT_TIMEOUT = "30s"
+_BACKOFF_START_SECONDS = 0.5
+_BACKOFF_MAX_SECONDS = 30.0
+# How often the listener wakes from a quiet connection to check whether it was asked to stop.
+_LISTEN_POLL_SECONDS = 1.0
+
+STREAM_HEADERS = {"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
+
+# Before a planned close, the last frame says why and how long the client should wait before reconnecting (ms).
+_RETRY_MS = {"max_age": 1000, "behind": 1000, "busy": 30_000}
+_SHUTDOWN_RETRY_MS = (1000, 5000)  # jittered, so a deploy's reconnects are spread out
+
+Read = Callable[..., Iterable[Event] | Awaitable[Iterable[Event]]]  # read(cursor) or read(cursor, wake)
+Start = Callable[[], Any]
+
+
+class TooManySubscribers(Exception):
+    """A cap is reached or the hub is shutting down. `Hub.sse` turns it into a 503 with Retry-After."""
+
+
+@dataclass(frozen=True, slots=True)
+class HubStats:
+    """
+    A snapshot for a health check or a metrics endpoint.
+
+    - `open_streams`: subscriptions currently open.
+    - `refused_total`, `dropped_total`: streams refused at a cap (or during shutdown) and streams ended for falling
+      behind, since the process started.
+    - `listener_connected`: the listener holds its LISTEN right now.
+    - `listener_reconnects_total`: how often the listener got its connection back after losing it.
+    - `last_notification_at`: Unix time of the last notification the listener received, or None if none yet.
+    """
+
+    open_streams: int
+    refused_total: int
+    dropped_total: int
+    listener_connected: bool
+    listener_reconnects_total: int
+    last_notification_at: float | None
+
+
+@dataclass(frozen=True, slots=True)
+class Wake:
+    """
+    Why `read` is running, for a `read(cursor, wake)`. Several causes can arrive together: a burst is one read.
+
+    - `start`: the stream's first read.
+    - `keys`: keys with a database notification since the last read.
+    - `signals`: labels from `hub.wake(key, signal=...)` since the last read.
+    - `resync`: the listener connected or reconnected, so anything may have changed.
+    - `reread`: nothing woke the stream for `reread_seconds`.
+    """
+
+    start: bool = False
+    keys: frozenset[str] = frozenset()
+    signals: frozenset[str] = frozenset()
+    resync: bool = False
+    reread: bool = False
+
+    @property
+    def data_may_have_changed(self) -> bool:
+        """True unless the only causes are `hub.wake` signals."""
+        return self.start or self.resync or self.reread or bool(self.keys)
+
+
+class Subscription:
+    """One stream's queue. `key` is what it watches, or None for every key. Touched only on the event loop."""
+
+    def __init__(self, key: str | None, owner: str | None, queue_size: int) -> None:
+        self.key = key
+        self.owner = owner
+        self.queue: asyncio.Queue[QueueItem] = asyncio.Queue(queue_size)
+        # What is queued, so a repeat of it is not queued again: the queue holds at most `queue_size` distinct items.
+        self._pending: set[QueueItem] = set()
+        self.ended = False
+
+    def offer(self, item: QueueItem) -> bool:
+        """Queues a wake-up. False when the queue was full, so this call ended the stream instead."""
+        if self.ended or item in self._pending:  # a duplicate wake-up adds nothing to the next read
+            return True
+        try:
+            self.queue.put_nowait(item)
+        except asyncio.QueueFull:
+            self._end(DROPPED)
+            return False
+        self._pending.add(item)
+        return True
+
+    def _end(self, marker: str) -> None:
+        """Replaces whatever is queued with a marker the stream reads as its last item."""
+        self.ended = True
+        while not self.queue.empty():
+            self.queue.get_nowait()
+        self._pending.clear()
+        self.queue.put_nowait(("marker", marker))
+
+    def close(self) -> None:
+        if not self.ended:
+            self._end(CLOSING)
+
+    async def wait(self, timeout: float) -> list[QueueItem] | None:  # noqa: ASYNC109 -- the ping interval, handed to wait_for
+        """Everything queued once there is anything (a burst costs one re-read), or None if the timeout came first."""
+        try:
+            first = await asyncio.wait_for(self.queue.get(), timeout)
+        except TimeoutError:
+            return None
+        items = [first]
+        while not self.queue.empty():
+            items.append(self.queue.get_nowait())
+        self._pending.difference_update(items)
+        return items
+
+
+class Hub:
+    """
+    Live updates for one NOTIFY channel.
+
+        hub = Hub(DIRECT_DATABASE_URL, channel="room_change")
+        app = FastAPI(lifespan=hub.lifespan)
+
+        @app.get("/rooms/{room}/stream")
+        async def stream(room: str, last_event_id: Annotated[str | None, Header()] = None):
+            return hub.sse(room, read=lambda after: read_after(room, after), cursor=..., start=...)
+
+    `conninfo` must be a direct connection: behind a transaction-mode pooler (PgBouncer in transaction mode, the
+    pooled URLs Supabase and Neon hand out) LISTEN succeeds and never delivers, and streams only update on their
+    periodic re-read.
+    """
+
+    def __init__(
+        self,
+        conninfo: str,
+        channel: str,
+        *,
+        max_subscribers: int = 500,
+        max_per_owner: int = 5,
+        queue_size: int = 64,
+        max_stream_seconds: float = 15 * 60,
+        ping_seconds: tuple[float, float] = (15.0, 25.0),
+        reread_seconds: float = 60.0,
+        json_default: Callable[[Any], Any] | None = None,
+        end_event: str | None = None,
+        handle_signals: bool = True,
+        listen_timeout: float | None = 5.0,
+    ) -> None:
+        if not channel or "\x00" in channel or len(channel.encode()) > 63:
+            raise ValueError("channel must be a non-empty identifier of at most 63 bytes")
+        if queue_size < 1:
+            raise ValueError("queue_size must be at least 1 (a zero-size asyncio queue is unbounded)")
+        if ping_seconds[0] <= 0 or ping_seconds[0] > ping_seconds[1]:
+            raise ValueError("ping_seconds must be (low, high) with 0 < low <= high")
+        if reread_seconds <= 0:
+            raise ValueError("reread_seconds must be greater than 0")
+        self.conninfo = conninfo
+        self.channel = channel
+        # Open streams per process; past it a stream is refused with a 503.
+        self.max_subscribers = max_subscribers
+        # Open streams per (key, owner), so one client cannot fill the process cap alone.
+        self.max_per_owner = max_per_owner
+        self.queue_size = queue_size
+        # A stream is authenticated once, when it opens; ending it after this long bounds how long a revoked session
+        # keeps one. The browser reconnects at once with Last-Event-ID.
+        self.max_stream_seconds = max_stream_seconds
+        # A stream sends a `: ping` comment this often while idle, so a proxy does not time the connection out. It
+        # costs no database read. Jittered so streams opened together do not all ping together. Keep a proxy's read
+        # timeout above the high end.
+        self.ping_seconds = ping_seconds
+        # A stream re-reads when nothing woke it for this long: the net under every lost notification, so the worst
+        # case for one is this delay. Streams read on their own clocks, so this is a steady trickle, not a spike.
+        self.reread_seconds = reread_seconds
+        # Passed to `json.dumps(default=...)` for Event data that is not JSON-native, e.g. `str` for datetimes.
+        self.json_default = json_default
+        # Before a planned close (age limit, shutdown, fell behind, busy) a stream always sends `retry:`, which
+        # EventSource applies by itself. With a name here it also sends that event with {"reason": ...}, for clients
+        # that are not EventSource and want to know why.
+        self.end_event = end_event
+        self.handle_signals = handle_signals
+        # How long `lifespan` waits for the first LISTEN before it lets the app start, so a health check and the first
+        # requests see a live listener. Startup proceeds either way: the listener keeps retrying and `stats` reports it.
+        self.listen_timeout = listen_timeout
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._subscriptions: set[Subscription] = set()
+        self._thread: threading.Thread | None = None
+        self._stop = threading.Event()
+        # Set while the listener holds a LISTEN: report it from a health check.
+        self.listening = threading.Event()
+        self.closing = False
+        self._signal_hooks: dict[signal.Signals, _SignalHook] = {}
+        self._refused = 0
+        self._dropped = 0
+        self._reconnects = 0
+        self._last_notification_at: float | None = None
+
+    def stats(self) -> HubStats:
+        return HubStats(
+            open_streams=len(self._subscriptions),
+            refused_total=self._refused,
+            dropped_total=self._dropped,
+            listener_connected=self.listening.is_set(),
+            listener_reconnects_total=self._reconnects,
+            last_notification_at=self._last_notification_at,
+        )
+
+    # --- streams --------------------------------------------------------------------------------
+
+    def stream(
+        self,
+        key: str | None,
+        read: Read,
+        *,
+        cursor: Any = None,
+        start: Start | None = None,
+        owner: str | None = None,
+        end_event: str | None = None,
+    ) -> AsyncIterator[str]:
+        """
+        The encoded SSE frames for one key (None: every key on the channel), for any framework to send as
+        `text/event-stream`.
+
+        - `read(cursor)` returns the events after `cursor`, oldest first, each with its `id` set to the cursor after
+          it. It may be a plain function (run in a thread) or async. It runs once at the start and again on every
+          wake-up and after `reread_seconds` of quiet, so it must be cheap when nothing changed. A `read` that takes
+          a second argument gets a `Wake` saying why it runs.
+        - `cursor` is where to start, already parsed from the client (Last-Event-ID or a query parameter). Validate it
+          first: it is client input.
+        - `start()` gives the current cursor when `cursor` is None, so the stream starts from now. It runs after the
+          subscription, so nothing written in between is missed. Without it, `read(None)` decides what None means.
+        - `owner` (a user id, a session) applies the per-owner cap. Streams without an owner have no such cap.
+        - `end_event`, when given, overrides the hub's: the event name sent with the reason before a planned close.
+
+        Call it from the event loop, after any 404 or permission check: the caps are checked here, so
+        `TooManySubscribers` is raised before any response exists. The stream subscribes when its first frame is read
+        and unsubscribes when it ends, however it ends.
+        """
+        self._require_loop()
+        self._check_caps(key, owner)
+        if end_event is None:
+            end_event = self.end_event
+        return self._events(key, owner, read, _accepts_wake(read), cursor, start, end_event)
+
+    def sse(
+        self,
+        key: str | None,
+        read: Read,
+        *,
+        cursor: Any = None,
+        start: Start | None = None,
+        owner: str | None = None,
+        end_event: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> "StreamingResponse":
+        """
+        `stream` as a Starlette/FastAPI `text/event-stream` response. Arguments as for `stream`; past a cap it raises
+        a 503 with `Retry-After: 30`. Needs `pip install "pg-sse[starlette]"`. Call it from an `async def` route.
+        """
+        try:
+            from starlette.exceptions import HTTPException
+            from starlette.responses import StreamingResponse
+        except ImportError:
+            raise ImportError('hub.sse needs Starlette: pip install "pg-sse[starlette]" (or use hub.stream)') from None
+        try:
+            frames = self.stream(key, read, cursor=cursor, start=start, owner=owner, end_event=end_event)
+        except TooManySubscribers as err:
+            logger.warning("pg_sse refused a stream (%s)", err)
+            raise HTTPException(
+                status_code=503, detail="Live updates are unavailable.", headers={"Retry-After": "30"}
+            ) from None
+        return StreamingResponse(frames, media_type="text/event-stream", headers={**STREAM_HEADERS, **(headers or {})})
+
+    async def _events(
+        self,
+        key: str | None,
+        owner: str | None,
+        read: Read,
+        wants_wake: bool,
+        cursor: Any,
+        start: Start | None,
+        end_event: str | None,
+    ) -> AsyncIterator[str]:
+        try:
+            subscription = self.subscribe(key, owner)
+        except TooManySubscribers:  # a cap filled, or shutdown began, since `stream` checked
+            yield _goodbye(end_event, "shutdown" if self.closing else "busy")
+            return
+        deadline = time.monotonic() + self.max_stream_seconds
+        try:
+            if cursor is None and start is not None:
+                cursor = await _call(start)
+            if cursor is not None:
+                # The browser reconnects from here even if no event ever arrives on this stream.
+                yield encode_cursor(cursor)
+            wake = Wake(start=True)
+            while True:
+                for event in await (_call(read, cursor, wake) if wants_wake else _call(read, cursor)):
+                    if not isinstance(event, Event):
+                        raise TypeError(f"read must return pg_sse.Event items, got {type(event).__name__}")
+                    yield encode(event, self.json_default)
+                    if event.id is not None:
+                        cursor = event.id
+                    if event.final:
+                        return
+                reread_at = time.monotonic() + self.reread_seconds
+                while True:  # idle: ping until something wakes the stream or a re-read is due
+                    now = time.monotonic()
+                    if now >= deadline:
+                        yield _goodbye(end_event, "max_age")
+                        return
+                    if now >= reread_at:
+                        wake = Wake(reread=True)
+                        break
+                    timeout = min(random.uniform(*self.ping_seconds), deadline - now, reread_at - now)  # noqa: S311 -- jitter
+                    woke = await subscription.wait(timeout)
+                    if woke is None:
+                        # Every timeout pings, even the one that leads to a re-read: the re-read may send nothing,
+                        # and the silence must never outlast a ping interval.
+                        if time.monotonic() < deadline:
+                            yield ": ping\n\n"
+                    elif subscription.ended:  # the marker is the only item left: dropped, or closed at shutdown
+                        yield _goodbye(end_event, "shutdown" if woke[0] == ("marker", CLOSING) else "behind")
+                        return
+                    else:
+                        wake = _wake_from(woke)
+                        break
+        except Exception:
+            logger.exception("pg_sse stream for key %r failed; the client reconnects", key)
+        finally:
+            self.unsubscribe(subscription)
+
+    # --- subscriptions (on the event loop) ---------------------------------------------------------
+
+    def subscribe(self, key: str | None, owner: str | None = None) -> Subscription:
+        """The low-level API under `stream`: a queue of notifications, wakes and markers. Unsubscribe in a `finally`."""
+        self._require_loop()
+        self._check_caps(key, owner)
+        subscription = Subscription(key, owner, self.queue_size)
+        self._subscriptions.add(subscription)
+        return subscription
+
+    def _check_caps(self, key: str | None, owner: str | None) -> None:
+        if self.closing:
+            self._refuse("shutting down")
+        if len(self._subscriptions) >= self.max_subscribers:
+            self._refuse("too many open streams")
+        # Without an owner there is nobody to cap: anonymous streams on one key are not one client.
+        if owner is not None and sum(1 for s in self._subscriptions if s.key == key and s.owner == owner) >= (
+            self.max_per_owner
+        ):
+            self._refuse("too many open streams for this owner")
+
+    def _refuse(self, reason: str) -> NoReturn:
+        self._refused += 1
+        raise TooManySubscribers(reason)
+
+    def unsubscribe(self, subscription: Subscription) -> None:
+        self._subscriptions.discard(subscription)
+
+    def wake(self, key: str, signal: str = "wake", *, all_keys: bool = True) -> None:
+        """
+        Wakes one key's streams for a change that is not a database write (someone is typing). Safe from any thread.
+
+        A `read(cursor, wake)` sees `signal` in `wake.signals`. With `all_keys=False` the streams watching every key
+        (`key=None`) are left alone: right for ephemeral per-key state that an all-keys view has nothing to show for.
+        """
+        self._post(self._dispatch, ("wake", key, signal), key, all_keys)
+
+    def close_all(self) -> None:
+        """Ends every stream and refuses new ones, so a shutdown does not wait out the graceful-shutdown timeout."""
+        self.closing = True
+        for subscription in list(self._subscriptions):
+            subscription.close()
+
+    def _require_loop(self) -> None:
+        try:
+            running = asyncio.get_running_loop()
+        except RuntimeError:
+            raise RuntimeError(
+                "pg_sse: call hub.stream(), hub.sse() or hub.subscribe() from an `async def` route"
+            ) from None
+        if self._loop is None:
+            raise RuntimeError(
+                "pg_sse: the hub is not running; use FastAPI(lifespan=hub.lifespan) or `async with hub.lifespan()`"
+            )
+        if running is not self._loop:
+            raise RuntimeError("pg_sse: the hub runs on another event loop")
+
+    def _dispatch(self, item: QueueItem, key: str | None = None, all_keys: bool = True) -> None:
+        """Offers `item` to the streams for `key` and (unless `all_keys` is False) the all-keys streams; to every
+        stream when `key` is None."""
+        for subscription in list(self._subscriptions):
+            if key is None or subscription.key == key or (all_keys and subscription.key is None):
+                self._offer(subscription, item)
+
+    def _offer(self, subscription: Subscription, item: QueueItem) -> None:
+        if not subscription.offer(item):
+            # Dropped for falling behind: its stream ends on its next read, and the hub forgets it now.
+            self._dropped += 1
+            self._subscriptions.discard(subscription)
+
+    # --- lifecycle --------------------------------------------------------------------------------
+
+    @asynccontextmanager
+    async def lifespan(self, _app: Any = None) -> AsyncIterator[None]:
+        """`FastAPI(lifespan=hub.lifespan)`, or `async with hub.lifespan():` inside your own lifespan."""
+        loop = asyncio.get_running_loop()
+        self.start(loop)
+        try:
+            if self.handle_signals:
+                self._install_signal_hook(loop)
+            if self.listen_timeout is not None:
+                await asyncio.to_thread(self.listening.wait, self.listen_timeout)
+            yield
+        finally:
+            self.close_all()
+            self._remove_signal_hook()
+            await asyncio.to_thread(self.stop)
+
+    def start(self, loop: asyncio.AbstractEventLoop | None = None) -> None:
+        if self._thread is not None:
+            return
+        self._loop = loop or asyncio.get_running_loop()
+        # One flag per start, held by its own thread: a listener that `stop` gave up waiting for (a hung connect) must
+        # never see the flag of a later start cleared and resume.
+        self._stop = threading.Event()
+        self.closing = False
+        self._thread = threading.Thread(target=self._listen, args=(self._stop,), name="pg-sse-listener", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        thread, self._thread = self._thread, None
+        if thread is None:
+            return
+        self._stop.set()
+        self.listening.clear()
+        thread.join(timeout=_LISTEN_POLL_SECONDS + 1)  # the listener checks the flag every poll
+
+    def _install_signal_hook(self, loop: asyncio.AbstractEventLoop) -> None:
+        """
+        uvicorn waits for open connections to finish before it runs the lifespan's shutdown, so an idle stream would
+        hold a deploy for the whole graceful-shutdown timeout. Chain onto SIGTERM/SIGINT (after the server installed
+        its own handlers) to end the streams the moment the signal arrives. A no-op off the main thread.
+        """
+        if threading.current_thread() is not threading.main_thread():
+            return
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            if sig in self._signal_hooks:
+                continue
+            previous = signal.getsignal(sig)
+            if previous == signal.SIG_DFL:
+                # The default action terminates the process at once, which already ends every stream. Nothing to
+                # shorten, and chaining would swallow the signal: a script with no server would never exit.
+                continue
+            hook = _SignalHook(previous)
+
+            def handler(signum: int, frame: FrameType | None, hook: _SignalHook = hook) -> None:
+                if hook.active and not loop.is_closed():
+                    loop.call_soon_threadsafe(self.close_all)
+                if callable(hook.previous):
+                    hook.previous(signum, frame)
+
+            hook.handler = handler
+            signal.signal(sig, handler)
+            self._signal_hooks[sig] = hook
+
+    def _remove_signal_hook(self) -> None:
+        """Puts the handlers back, so entering `lifespan` again does not stack another layer on this one."""
+        for sig, hook in self._signal_hooks.items():
+            # Someone wrapped a handler around ours since (another hub, say): removing ours would remove theirs too, so
+            # ours stays in the chain, inert, and only passes the signal on.
+            hook.active = False
+            if hook.previous is not None and signal.getsignal(sig) is hook.handler:
+                signal.signal(sig, hook.previous)
+        self._signal_hooks.clear()
+
+    # --- the listener thread ----------------------------------------------------------------------
+
+    def _post(self, callback: Callable[..., None], *args: Any) -> None:
+        loop = self._loop
+        if loop is not None and not loop.is_closed():
+            with contextlib.suppress(RuntimeError):  # the loop closed between the check and the call
+                loop.call_soon_threadsafe(callback, *args)
+
+    def _listen(self, stop: threading.Event) -> None:
+        settings: dict[str, Any] = dict(_TCP_KEEPALIVES)
+        if "connect_timeout" not in conninfo_to_dict(self.conninfo):
+            settings["connect_timeout"] = _CONNECT_TIMEOUT_SECONDS
+        conninfo = make_conninfo(self.conninfo, **settings)
+        backoff = _BACKOFF_START_SECONDS
+        connected_before = False
+        while not stop.is_set():
+            try:
+                with psycopg.connect(conninfo, autocommit=True, application_name="pg-sse-listener") as conn:
+                    if stop.is_set():  # `stop` gave up on this thread while it was connecting: it is not the listener
+                        return
+                    conn.execute(f"SET statement_timeout = '{_STATEMENT_TIMEOUT}'")
+                    conn.execute(sql.SQL("LISTEN {}").format(sql.Identifier(self.channel)))
+                    backoff = _BACKOFF_START_SECONDS
+                    if connected_before:
+                        self._reconnects += 1
+                    connected_before = True
+                    # Anything committed before this LISTEN existed (first connect or reconnect) was missed: every
+                    # stream re-reads. Posted before `listening` is set, so whoever sees it set subscribes after the
+                    # marker has been dispatched. With no stream open yet it is a no-op.
+                    self._post(self._dispatch, ("marker", RESYNC))
+                    self.listening.set()
+                    last_checked = time.monotonic()
+                    while not stop.is_set():
+                        if time.monotonic() - last_checked >= _KEEPALIVE_QUERY_SECONDS:
+                            conn.execute("SELECT 1")
+                            last_checked = time.monotonic()
+                        for notification in conn.notifies(timeout=_LISTEN_POLL_SECONDS):
+                            self._last_notification_at = time.time()
+                            self._post(self._dispatch, ("notify", notification.payload), notification.payload)
+            except Exception:
+                if stop.is_set():  # `stop` already cleared `listening`; a later start may have set it again
+                    return
+                self.listening.clear()
+                logger.warning("pg_sse listener lost its connection; retrying in %.1fs", backoff, exc_info=True)
+                connected_before = True
+                stop.wait(backoff * random.uniform(0.5, 1.0))  # noqa: S311 -- reconnect jitter
+                backoff = min(backoff * 2, _BACKOFF_MAX_SECONDS)
+
+
+@dataclass(slots=True)
+class _SignalHook:
+    """A handler this hub installed over `previous`. Once `active` is False it only passes the signal on."""
+
+    previous: Any
+    handler: Callable[[int, FrameType | None], None] | None = None
+    active: bool = True
+
+
+def _goodbye(event_name: str | None, reason: str) -> str:
+    retry_ms = random.randint(*_SHUTDOWN_RETRY_MS) if reason == "shutdown" else _RETRY_MS[reason]  # noqa: S311
+    return encode_goodbye(event_name, reason, retry_ms)
+
+
+def _wake_from(items: list[QueueItem]) -> Wake:
+    keys = frozenset(item[1] for item in items if item[0] == "notify")
+    signals = frozenset(item[2] for item in items if item[0] == "wake")
+    return Wake(keys=keys, signals=signals, resync=("marker", RESYNC) in items)
+
+
+def _accepts_wake(fn: Callable[..., Any]) -> bool:
+    """
+    Whether `read` is read(cursor, wake): its second positional parameter is named `wake` or has no default. A
+    defaulted second parameter of another name (`limit=500`) is not a wake, and neither is `*args`. Handles lambdas,
+    partials (their bound arguments are gone from the signature) and methods.
+    """
+    try:
+        parameters = inspect.signature(fn).parameters.values()
+    except (TypeError, ValueError):  # no signature available (some builtins): assume read(cursor)
+        return False
+    positional = [p for p in parameters if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
+    if len(positional) < 2:
+        return False
+    second = positional[1]
+    return second.name == "wake" or second.default is second.empty
+
+
+async def _call(fn: Callable[..., Any], *args: Any) -> Any:
+    """Awaits an async callable on the loop; runs a plain one in a thread (a lambda returning a coroutine works too)."""
+    if inspect.iscoroutinefunction(fn):
+        return await fn(*args)
+    result = await asyncio.to_thread(fn, *args)
+    if inspect.isawaitable(result):
+        return await result
+    return result

pg_sse/_sql.py

@@ -0,0 +1,108 @@
+import re
+
+_IDENTIFIER = re.compile(r"^[a-z_][a-z0-9_]{0,62}$")
+
+
+def trigger_sql(table: str, key_column: str, channel: str, *, order_column: str | None = None) -> str:
+    """
+    The SQL that wires a table to a channel: run it once, in a migration.
+
+    - A notify trigger sends `pg_notify(channel, key)` for every inserted, updated or deleted row (both keys when an
+      update moves a row). A trigger, not a call in each writer, so a cron job or a psql session cannot forget it.
+      NOTIFY is delivered on commit: a rolled-back write announces nothing.
+    - With `order_column` (a serial, bigserial or identity column, usually `id`), a second trigger makes that column
+      follow commit order within a key: an insert locks its key until it commits, then draws the next value. Without
+      it, a reader at cursor 11 can skip id 10 committing late. The trigger replaces any value an INSERT supplies.
+
+    The order trigger takes an advisory lock on the key until the inserting transaction ends, so other inserts to
+    that key wait, and two transactions inserting into keys in opposite order can deadlock: keep that transaction
+    short. The lock is `pg_advisory_xact_lock(hashtext(channel), hashtext(key))`, and advisory locks share one
+    namespace per database, so an application taking the same two-int lock would serialise against these inserts.
+    `hashtext` is 32-bit, so two different keys can collide and briefly make each other's inserts wait: a delay,
+    never wrong ids.
+
+    Names are plain lower-case identifiers; `table` may be `schema.table`. Postgres 14 or later. The objects it creates
+    are named `"pg_sse$notify$<table>$<key_column>"` and `"pg_sse$order$<table>$<order_column>"`: a trigger and a
+    function each, in the table's schema.
+    """
+    name, qualified, prefix = _parse(table, key_column, channel, order_column)
+    notify_fn = _name("pg_sse", "notify", name, key_column)
+    statements = []
+    if order_column:
+        # Without a sequence the first insert would fail on a null id; fail when the trigger is installed instead.
+        statements.append(f"""DO $pg_sse$
+BEGIN
+    IF pg_get_serial_sequence('{qualified}', '{order_column}') IS NULL THEN
+        RAISE EXCEPTION 'pg_sse: {qualified}."{order_column}" has no sequence; '
+            'order_column must be serial, bigserial or identity';
+    END IF;
+END
+$pg_sse$;""")
+    statements += [
+        f"""CREATE OR REPLACE FUNCTION {prefix}"{notify_fn}"() RETURNS trigger LANGUAGE plpgsql AS $pg_sse$
+BEGIN
+    IF TG_OP = 'DELETE' THEN
+        PERFORM pg_notify('{channel}', OLD."{key_column}"::text);
+        RETURN OLD;
+    END IF;
+    IF TG_OP = 'UPDATE' AND OLD."{key_column}" IS DISTINCT FROM NEW."{key_column}" THEN
+        PERFORM pg_notify('{channel}', OLD."{key_column}"::text);
+    END IF;
+    PERFORM pg_notify('{channel}', NEW."{key_column}"::text);
+    RETURN NEW;
+END;
+$pg_sse$;""",
+        f'CREATE OR REPLACE TRIGGER "{notify_fn}" AFTER INSERT OR UPDATE OR DELETE ON {qualified} '
+        f'FOR EACH ROW EXECUTE FUNCTION {prefix}"{notify_fn}"();',
+    ]
+    if order_column:
+        order_fn = _name("pg_sse", "order", name, order_column)
+        statements += [
+            f"""CREATE OR REPLACE FUNCTION {prefix}"{order_fn}"() RETURNS trigger LANGUAGE plpgsql AS $pg_sse$
+BEGIN
+    PERFORM pg_advisory_xact_lock(hashtext('{channel}'), hashtext(NEW."{key_column}"::text));
+    NEW."{order_column}" := nextval(pg_get_serial_sequence('{qualified}', '{order_column}'));
+    RETURN NEW;
+END;
+$pg_sse$;""",
+            f'CREATE OR REPLACE TRIGGER "{order_fn}" BEFORE INSERT ON {qualified} '
+            f'FOR EACH ROW EXECUTE FUNCTION {prefix}"{order_fn}"();',
+        ]
+    return "\n\n".join(statements) + "\n"
+
+
+def drop_trigger_sql(table: str, key_column: str, *, order_column: str | None = None) -> str:
+    """The SQL that undoes `trigger_sql` (same arguments, no channel needed): for a downgrade migration."""
+    name, qualified, prefix = _parse(table, key_column, None, order_column)
+    names = [_name("pg_sse", "notify", name, key_column)]
+    if order_column:
+        names.append(_name("pg_sse", "order", name, order_column))
+    statements = []
+    for fn in names:
+        statements += [f'DROP TRIGGER IF EXISTS "{fn}" ON {qualified};', f'DROP FUNCTION IF EXISTS {prefix}"{fn}"();']
+    return "\n".join(statements) + "\n"
+
+
+def _parse(table: str, key_column: str, channel: str | None, order_column: str | None) -> tuple[str, str, str]:
+    """Validates the identifiers; returns the table name, the quoted table and the quoted schema prefix."""
+    schema, _, name = table.rpartition(".")
+    parts = [name, key_column, *([schema] if schema else [])]
+    parts += [part for part in (channel, order_column) if part is not None]
+    for part in parts:
+        _check(part)
+    qualified = f'"{schema}"."{name}"' if schema else f'"{name}"'
+    prefix = f'"{schema}".' if schema else ""
+    return name, qualified, prefix
+
+
+def _check(identifier: str) -> None:
+    if not _IDENTIFIER.match(identifier):
+        raise ValueError(f"pg_sse: {identifier!r} is not a plain lower-case identifier (a-z, 0-9, _; at most 63 bytes)")
+
+
+def _name(*parts: str) -> str:
+    # `$` is legal in a PostgreSQL identifier and cannot appear in a validated one, so no two tables share a name.
+    name = "$".join(parts)
+    if len(name) > 63:
+        raise ValueError(f"pg_sse: the generated name {name!r} is longer than 63 bytes; shorten the table or column")
+    return name

pg_sse-0.1.0.dist-info/METADATA

@@ -0,0 +1,309 @@
+Metadata-Version: 2.5
+Name: pg-sse
+Version: 0.1.0
+Summary: Live updates from the Postgres you already run: LISTEN/NOTIFY wake-ups, re-reads from a cursor, served as server-sent events from any async Python framework (Starlette and FastAPI built in).
+Project-URL: Homepage, https://github.com/sandhusanthakumar/pg-sse
+Project-URL: Issues, https://github.com/sandhusanthakumar/pg-sse/issues
+Project-URL: Changelog, https://github.com/sandhusanthakumar/pg-sse/blob/main/CHANGELOG.md
+Author: Sandhu Santhakumar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,listen,notify,postgres,postgresql,realtime,server-sent-events,sse,starlette
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: psycopg>=3.2.1
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: starlette
+Requires-Dist: starlette>=0.36; extra == 'starlette'
+Description-Content-Type: text/markdown
+
+# pg-sse
+
+[![CI](https://github.com/sandhusanthakumar/pg-sse/actions/workflows/ci.yml/badge.svg)](https://github.com/sandhusanthakumar/pg-sse/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pg-sse)](https://pypi.org/project/pg-sse/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pg-sse)](https://pypi.org/project/pg-sse/)
+[![License](https://img.shields.io/pypi/l/pg-sse)](LICENSE)
+
+Live updates from the Postgres you already run. No Redis, no broker, no WebSocket service: a table trigger sends `NOTIFY`, one listener per process wakes the open streams, and each stream re-reads from its cursor and sends server-sent events. Works with Starlette and FastAPI out of the box, and with any other framework through `hub.stream`.
+
+```sh
+pip install "pg-sse[starlette]"   # or "pg-sse[fastapi]"; plain "pg-sse" is enough for hub.stream
+pip install "psycopg[binary]"     # on a machine without libpq; see the psycopg install docs for the alternatives
+```
+
+## The one rule
+
+A notification carries only a key (a room id, a conversation id) and means **"something changed here, re-read from your cursor"**. It never carries the data. So a lost notification costs a delay, never an event, and there's no 8000-byte payload limit to hit.
+
+## Why not X
+
+- **Polling.** Every client hits the database on a timer, so load grows with clients times frequency, and latency is half the interval. Here an idle stream costs one read a minute, and a write reaches clients within milliseconds.
+- **WebSockets.** You usually end up running a second service and writing your own reconnect and catch-up logic. `EventSource` reconnects by itself and sends `Last-Event-ID`, and one-way updates are all most pages need.
+- **Redis pub/sub.** It is another system to run, secure and keep consistent with your database, and a message missed during a disconnect is gone. Here the database is the source of truth and a missed wake-up costs a delay.
+- **Supabase Realtime.** It ties you to one vendor's platform and its protocol. This runs against any Postgres 14+ you can open a direct connection to.
+
+## Use it
+
+**1. Once, in a migration:** wire the table to a channel.
+
+```python
+from pg_sse import trigger_sql
+
+conn.execute(trigger_sql("messages", key_column="room", channel="room_change", order_column="id"))
+```
+
+That creates two triggers:
+
+| Trigger | Why |
+|---|---|
+| `pg_notify('room_change', room)` after every insert, update and delete | No writer can forget it: not a cron job, not a psql session. Delivered on commit; a rollback announces nothing. |
+| With `order_column` (a serial, bigserial or identity column): ids follow commit order within a key | Without it, a reader at cursor 11 can skip id 10 committing late. An insert locks its key until it commits, then draws the next id (see Limits for the cost). |
+
+**2. The app:**
+
+```python
+from typing import Annotated
+from fastapi import FastAPI, Header
+from pg_sse import Event, Hub
+
+hub = Hub(DIRECT_DATABASE_URL, channel="room_change")  # a direct connection, not a pooled one
+app = FastAPI(lifespan=hub.lifespan)
+
+
+def read_after(room: str, after: int) -> list[Event]:
+    rows = db.fetch("SELECT id, body FROM messages WHERE room = %s AND id > %s ORDER BY id LIMIT 500", (room, after))
+    return [Event({"id": id, "body": body}, id=id) for id, body in rows]
+
+
+def latest_id(room: str) -> int:
+    return db.fetchval("SELECT coalesce(max(id), 0) FROM messages WHERE room = %s", (room,))
+
+
+@app.get("/rooms/{room}/stream")
+async def stream(room: str, last_event_id: Annotated[str | None, Header()] = None):
+    cursor = int(last_event_id) if last_event_id and last_event_id.isdigit() else None  # client input: parse it
+    return hub.sse(room, read=lambda after: read_after(room, after), cursor=cursor, start=lambda: latest_id(room))
+```
+
+**3. The browser:**
+
+```js
+const source = new EventSource("/rooms/lobby/stream");
+source.onmessage = (e) => render(JSON.parse(e.data));
+```
+
+`EventSource` reconnects by itself and sends `Last-Event-ID`; the stream catches up from there.
+
+A full runnable app, with async reads on a connection pool and a browser page: [examples/chat.py](examples/chat.py).
+
+## Other frameworks
+
+`hub.sse` is a thin wrapper over `hub.stream`, which yields encoded SSE frames (`str`) and knows nothing about Starlette. It raises `TooManySubscribers` at the call, before any response exists, so turn that into your framework's 503. The Django and Litestar snippets below are illustrative, not tested in CI.
+
+```python
+# Django (ASGI; run the hub's lifespan from your ASGI app or a lifespan wrapper)
+from django.http import HttpResponse, StreamingHttpResponse
+
+
+async def stream(request, room):
+    try:
+        frames = hub.stream(room, read=lambda after: read_after(room, after), start=lambda: latest_id(room))
+    except TooManySubscribers:
+        return HttpResponse(status=503, headers={"Retry-After": "30"})
+    return StreamingHttpResponse(frames, content_type="text/event-stream", headers={"Cache-Control": "no-cache"})
+```
+
+```python
+# Litestar
+from litestar import get
+from litestar.response import Stream
+
+
+@get("/rooms/{room:str}/stream")
+async def stream(room: str) -> Stream:
+    frames = hub.stream(room, read=lambda after: read_after(room, after), start=lambda: latest_id(room))
+    return Stream(
+        frames, media_type="text/event-stream", headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
+    )
+```
+
+Aiohttp and Quart work the same way: write each frame to the response as it arrives.
+
+## Signal streams
+
+A stream doesn't have to carry data. It can tell the page *what* to refetch: "this list changed", "only the typing indicator changed", "you may have missed something, refetch everything". For that, give `read` a second parameter named `wake` (or a required second parameter). It receives a `Wake` that says why the read is running; several causes can arrive together, since a burst is one read.
+
+| Field | Meaning |
+|---|---|
+| `start` | The stream's first read. |
+| `keys` | Keys with a database notification since the last read. |
+| `signals` | Labels from `hub.wake(key, signal=...)` since the last read. |
+| `resync` | The listener connected or reconnected: anything may have changed. |
+| `reread` | Nothing woke the stream for `reread_seconds`. |
+
+`wake.data_may_have_changed` is True unless the only causes are `hub.wake` signals.
+
+```python
+from pg_sse import Event, Wake
+
+
+def signals(cursor, wake: Wake) -> list[Event]:
+    if wake.start:
+        return [Event({}, event="ready")]  # the page loads everything once
+    if wake.resync or wake.reread:
+        return [Event({}, event="resync")]  # anything may have changed
+    if wake.keys:
+        return [Event({"keys": sorted(wake.keys)}, event="change")]
+    if "typing" in wake.signals:
+        return [Event({}, event="typing")]  # refetch only the typing indicator
+    return []
+
+
+@app.get("/inbox/stream")
+async def inbox(user: User = Depends(current_user)):
+    return hub.sse(None, read=signals, owner=user.id)  # every key on the channel
+
+
+# elsewhere, from any thread:
+hub.wake(room_id, signal="typing", all_keys=False)
+```
+
+A one-parameter `read(cursor)` works too, and so does one whose second parameter has a default under another name (`read(after, limit=500)`): only a parameter named `wake`, or a required one, receives the `Wake`. `hub.wake(key)` reaches the streams for `key` and the all-keys streams (`key=None`); `all_keys=False` keeps it on its key, which is right for ephemeral per-key state (typing, presence, a cursor position) that an all-keys view has nothing to show for. Database notifications always reach the all-keys streams: they report real writes.
+
+## What `hub.sse` does for you
+
+- **Subscribes before the catch-up read**, so a write between the two is a queued wake-up, not a gap.
+- **Calls `start()` after subscribing** when there's no cursor, and sends that cursor as the first frame's `id`, so a reconnect resumes from it even if no event arrived.
+- **Re-reads on every wake-up**, and a burst of notifications costs one read.
+- **Pings every 15–25 s** (`ping_seconds`) with an SSE comment, so proxies do not time an idle stream out. A ping costs no database read.
+- **Re-reads after 60 s of quiet** (`reread_seconds`) even when nothing woke it. This is the safety net under every lost notification: the worst case is a one-minute delay.
+- **Wakes every stream after the listener connects or reconnects**, since anything committed before its LISTEN existed (at startup, or while it was down) was missed. Reconnects with backoff; a `SELECT 1` every minute and TCP keepalives catch a half-open connection.
+- **Bounded queue per stream** (64). Identical wake-ups are queued once, so a hot key costs one slot, not one per write. A stream ends, rather than buffers, when more than `queue_size` distinct keys or signals arrive during one read (only an all-keys stream on a wide channel gets there); the browser reconnects and catches up.
+- **Caps** open streams per process (500) and, when you pass `owner`, per key and owner (5). Past a cap, `hub.sse` raises a `503` with `Retry-After: 30`. Without `owner`, one client can hold every slot in a worker; pass `owner` (user id, session, or client address) on public endpoints.
+- **Ends streams after 15 minutes.** A stream is authenticated once, when it opens; this bounds how long a revoked session keeps one.
+- **Ends every stream on SIGTERM**, so a deploy doesn't wait out uvicorn's graceful-shutdown timeout. It chains onto the server's handler; with no handler installed (a plain script) the default action is left alone and ends the process as usual.
+- **Says goodbye before a planned close.** The last frame carries `retry:`, which `EventSource` applies by itself, and, with `end_event` set, a named event with the reason:
+
+| Reason | When | `retry` (ms) | What the client should do |
+|---|---|---|---|
+| `max_age` | The stream reached `max_stream_seconds`. | 1000 | Reconnect now, with its cursor. |
+| `shutdown` | SIGTERM, or the lifespan ending. | 1000–5000, random | Reconnect after the delay. The jitter spreads a deploy's reconnects out. |
+| `behind` | The stream's queue filled. | 1000 | Reconnect and catch up from its cursor. |
+| `busy` | A cap filled between the check in `hub.sse` and the stream starting. | 30000 | Back off, as for a `503` with `Retry-After: 30`. |
+
+There is no goodbye after `Event(final=True)`, since the application already said what it meant, or when `read` raised, since the stream's state is unknown and an abrupt close is the honest signal.
+
+```js
+// EventSource: nothing to write. `retry` is applied automatically; the reason is there if you want it.
+source.addEventListener("end", (e) => console.debug("stream ended:", JSON.parse(e.data).reason));
+```
+
+```ts
+// A fetch-based reader decides for itself.
+if (event.event === "end") {
+  const { reason } = JSON.parse(event.data);
+  scheduleReconnect(reason === "busy" ? 30_000 : event.retry ?? 1_000);
+}
+```
+
+## API
+
+| | |
+|---|---|
+| `Hub(conninfo, channel, *, max_subscribers=500, max_per_owner=5, queue_size=64, max_stream_seconds=900, ping_seconds=(15, 25), reread_seconds=60, json_default=None, end_event=None, handle_signals=True, listen_timeout=5.0)` | One per channel per process. `max_per_owner` applies only to streams opened with an `owner`; anonymous streams are limited by `max_subscribers` alone. `queue_size` must be at least 1. `json_default` is `json.dumps`'s `default` for `Event` data that is not JSON-native: `json_default=str` is the common choice for datetimes, UUIDs and Decimals. `end_event` names the event sent with the reason before a planned close; off by default, the `retry:` alone is always sent. `listen_timeout` is how many seconds `lifespan` waits for the first LISTEN before the app starts (`None`: do not wait); it never fails startup. |
+| `hub.lifespan` | `FastAPI(lifespan=hub.lifespan)`, or `async with hub.lifespan():` inside your own lifespan. Chains onto an existing SIGTERM/SIGINT handler (a default action is left alone) and restores it when it exits. Starts without a database: the listener keeps retrying and `listener_connected` says whether it is live. |
+| `hub.stream(key, read, *, cursor=None, start=None, owner=None, end_event=None)` | The primary API: an async iterator of encoded SSE frames, for any framework. `key=None` streams every key on the channel. `key` is the text form of the key column (`str(room_id)` for an integer column): the notification payload is `key::text`, and a NULL key notifies `""`. `read` takes `(cursor)` or `(cursor, wake)`, and returns a list, not a generator: a generator would run its queries on the event loop. It and `start` may be plain functions (run in a thread) or async. `end_event` overrides the hub's. Raises `TooManySubscribers` when it is called. |
+| `hub.sse(key, read, *, cursor=None, start=None, owner=None, end_event=None, headers=None)` | `stream` as a Starlette/FastAPI response (needs the `starlette` extra). Past a cap it raises a 503 with `Retry-After`. |
+| `Event(data, id=None, event=None, final=False)` | `data`: a str as is, anything else as JSON. `id`: the cursor after this event, handed back to `read` unchanged. `final=True` ends the stream after it (a closed conversation). |
+| `Wake(start=False, keys=frozenset(), signals=frozenset(), resync=False, reread=False)` | Why `read` runs, for a `read(cursor, wake)`. `data_may_have_changed` is True unless the only causes are `hub.wake` signals. |
+| `hub.wake(key, signal="wake", *, all_keys=True)` | Wakes one key's streams for a change that isn't a database write (someone is typing). Safe from any thread. `signal` shows up in `wake.signals`; `all_keys=False` leaves the all-keys streams alone. |
+| `hub.stats()` | A frozen `HubStats`: `open_streams`, `refused_total`, `dropped_total`, `listener_connected`, `listener_reconnects_total`, `last_notification_at` (Unix time or `None`). Counters are per process and start at zero. |
+| `hub.listening` | A `threading.Event`, set while the listener holds its LISTEN. `hub.stats().listener_connected` says the same. |
+| `hub.subscribe(key, owner)` / `hub.unsubscribe(s)` | The low-level queue under `stream`, for a custom stream loop. |
+| `trigger_sql(table, key_column, channel, *, order_column=None)` | The trigger SQL. Plain lower-case names; `table` may be `schema.table`. `order_column` must be a serial, bigserial or identity column; installing fails with a clear error otherwise. Creates a function and a trigger named `"pg_sse$notify$<table>$<key>"` (and `"pg_sse$order$<table>$<order_column>"`), which is what you will see in `\d`. Postgres 14+. |
+| `drop_trigger_sql(table, key_column, *, order_column=None)` | The SQL that removes what `trigger_sql` created, for a downgrade migration. |
+
+### Health check
+
+```python
+import dataclasses
+
+from fastapi.responses import JSONResponse
+
+
+@app.get("/healthz")
+async def healthz():
+    stats = hub.stats()
+    return JSONResponse(dataclasses.asdict(stats), status_code=200 if stats.listener_connected else 503)
+```
+
+## Testing your app
+
+The hub needs a real Postgres; there is nothing to mock, because the database is the source of truth. Point the tests at a scratch database and enter the hub's lifespan. Starlette's `TestClient` runs the lifespan off the main thread, where the signal hook is skipped anyway, but pass `handle_signals=False` in tests so a test never touches the process's signal handlers.
+
+```python
+hub = Hub(TEST_DSN, channel="room_change", handle_signals=False)
+with TestClient(app) as client:  # runs the lifespan
+    ...
+```
+
+## Multiple workers
+
+Each process (each uvicorn or gunicorn worker) holds one LISTEN connection and its own caps and counters. Nothing is shared between workers and nothing needs to be: Postgres delivers every notification to every listener, and each worker wakes its own streams. Budget one connection per worker.
+
+## Limits
+
+- **LISTEN needs a direct connection.** Behind a transaction-mode pooler (PgBouncer in transaction mode, the pooled connection strings Supabase and Neon give out) LISTEN succeeds and nothing ever arrives; streams then update only on the re-read. Give the hub the direct URL; your queries can still use the pooler.
+- **The cursor sees new rows, not updates.** If a stream must show edits, have `read` return the current state alongside new rows, or use a cursor that moves on update (a version column with `order_column`).
+- **Sync reads run in a thread pool.** A plain-function `read` or `start` runs in asyncio's default executor (`min(32, cpu + 4)` threads), and under Starlette other sync routes share anyio's pool of 40. Hundreds of streams re-reading at once queue behind it. Prefer async `read` and `start` on an `psycopg_pool.AsyncConnectionPool`; see [examples/chat.py](examples/chat.py). Use `functools.partial(read_after, room)` rather than a lambda to keep an async function off the pool.
+- **`order_column` serialises inserts per key.** The ordering trigger takes `pg_advisory_xact_lock` on the key and holds it until the transaction ends, so every other insert to that key waits for the whole transaction. Two transactions inserting into keys in opposite order can deadlock, and Postgres aborts one of them. Keep the transaction that inserts short, or skip `order_column` and tolerate a late id arriving on the next re-read. The lock is `pg_advisory_xact_lock(hashtext(channel), hashtext(key))`; advisory locks share one namespace per database, so an application taking the same two-int lock would serialise against these inserts, and since `hashtext` is 32-bit two different keys can collide and briefly wait on each other (a delay, never wrong ids).
+- **Per process.** Each worker runs its own listener, which works, but the caps are per process.
+- **The database may be down at startup.** `lifespan` waits up to `listen_timeout` for the first LISTEN and then starts anyway; until the listener connects, streams update on their re-read and `listener_connected` is false.
+- **Disconnect detection depends on the server.** Starlette 1.7 under an ASGI server that advertises `spec_version` 2.4 no longer listens for `http.disconnect` during a streaming response: a dead client is noticed at the next write, at most `ping_seconds[1]` later, and its slot is held until then. uvicorn 0.54 advertises 2.3 and frees the slot at once.
+- **psycopg 3** for the listener; your own queries can use any driver.
+- **A framework for the response.** `hub.sse` needs Starlette or FastAPI; any other framework uses `hub.stream`.
+
+## For AI coding agents
+
+If you are generating code with this library, follow these rules:
+
+1. Run `trigger_sql(table, key_column, channel, order_column="id")` once in a migration. Do not call `pg_notify` from application code, and do not put row data in a notification.
+2. Give `Hub` a **direct** database URL (not a pooled / PgBouncer / Supabase port 6543 / Neon `-pooler` URL).
+3. Register the hub with `FastAPI(lifespan=hub.lifespan)`, or `async with hub.lifespan():` inside an existing lifespan.
+4. Call `hub.sse(...)` (Starlette/FastAPI) or `hub.stream(...)` (any framework; catch `TooManySubscribers`) from an `async def` route, after any 404 or permission check.
+5. `read(after)` returns `pg_sse.Event` items **after** the cursor, oldest first, each with `id` set. Use `WHERE id > %s ORDER BY id LIMIT n`.
+6. Parse `Last-Event-ID` before passing it as `cursor`; it is client input.
+7. Pass `start=` (the current max id) when the stream should start from now. Do not compute it before calling `hub.sse`: that reintroduces a gap.
+8. Prefer async `read` and `start` on a connection pool; plain functions run in a limited thread pool.
+9. In the browser use `EventSource`; it resumes with `Last-Event-ID` by itself.
+10. `read(cursor, wake)` is optional: use it only when the stream must tell the client *what kind* of change happened (see Signal streams). A stream that sends rows keeps `read(cursor)`.
+11. Use `hub.wake(key, signal=..., all_keys=False)` for ephemeral per-key state (typing, presence). The default also wakes the all-keys streams.
+12. Set `Hub(end_event="end")` when the client is not `EventSource`, so it can read the reason and the retry before a planned close.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). In short:
+
+```sh
+uv sync
+PG_SSE_TEST_DSN=postgresql://sse:sse@127.0.0.1:55432/pg_sse_test uv run pytest --cov
+uv run ruff check . && uv run mypy
+```
+
+The tests create and drop a schema per test in the database you point them at; use a scratch database.
+
+## License
+
+MIT

pg_sse-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pg_sse/__init__.py,sha256=LcjoW4M-tZv9oMJ-OLE6d3k_wfL-3iclyXKjTpt-3eE,472
+pg_sse/_event.py,sha256=7bQI8DQKaUt2jgsIokhdM4YaD3uK7CtwQ7Fi8PloNXI,2540
+pg_sse/_hub.py,sha256=jDxT47BvUhShWhPtQnf33gjRQoE7avekIN5g8JAouH4,29702
+pg_sse/_sql.py,sha256=sqb0RDhVL9u0uXxUz4t_p-RDuZD0HzZGo08vq06kLDo,5485
+pg_sse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pg_sse-0.1.0.dist-info/METADATA,sha256=EN4GOej_p-ahGEzJ_YinQjID60PPG4Ts5nuutQcaywE,21934
+pg_sse-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pg_sse-0.1.0.dist-info/licenses/LICENSE,sha256=Ml3YR3qGMwvxt9lCtrt3Gr00WiNPwOYWPRC4kaU82ao,1075
+pg_sse-0.1.0.dist-info/RECORD,,

pg_sse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pg_sse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandhu Santhakumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.