pgnudge 1.0.0__py3-none-any.whl

pgnudge/__init__.py

@@ -0,0 +1,17 @@
+"""Push-only change nudges from PostgreSQL; nothing on the server outlives the connection."""
+
+from pgnudge.core import Batch, Event, FeedItem, Resync
+from pgnudge.proto import PgServerError
+from pgnudge.wal import WalFeed
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Batch",
+    "Event",
+    "FeedItem",
+    "PgServerError",
+    "Resync",
+    "WalFeed",
+    "__version__",
+]

pgnudge/core.py

@@ -0,0 +1,39 @@
+"""Feed contract: the two item types every feed emits.
+
+``Resync`` (reload everything) and ``Batch`` (coalesced wakeups) —
+at-least-once, every gap bracketed by a Resync. See README.
+"""
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+__all__ = ["Event", "Batch", "Resync", "FeedItem"]
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """One coalesced wakeup; ``count`` = arrivals of this payload in the window."""
+
+    payload: str
+    first_seen: float  # time.time() of first arrival in this batch
+    count: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class Batch:
+    """A debounce window's worth of events, deduplicated, in arrival order."""
+
+    events: tuple[Event, ...]
+
+    def payloads(self) -> tuple[str, ...]:
+        return tuple(e.payload for e in self.events)
+
+
+@dataclass(frozen=True, slots=True)
+class Resync:
+    """Reload-everything signal; reason is "connected" | "reconnected" | "overflow" | "failsafe"."""
+
+    reason: str
+
+
+FeedItem: TypeAlias = Resync | Batch

pgnudge/engine.py

@@ -0,0 +1,286 @@
+"""The machinery behind a feed, one class per concern, pure stdlib.
+
+``Intake`` buffers raw wakeups, ``Coalescer`` dedups them, ``Debouncer``
+decides when a window closes, ``Backoff`` paces reconnects, and
+``FeedService`` wires them together behind the async-iterator surface
+that ``BaseFeed`` exposes.
+"""
+
+import asyncio
+import contextlib
+import random
+import time
+from collections.abc import AsyncIterator, Callable, Coroutine
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Self
+
+from pgnudge.core import Batch, Event, FeedItem, Resync
+
+__all__ = ["Wakeup", "Intake", "Coalescer", "Debouncer", "Backoff", "FeedService", "BaseFeed"]
+
+
+@dataclass(frozen=True, slots=True)
+class Wakeup:
+    """One raw arrival from a transport, pre-coalescing."""
+
+    payload: str
+    at: float  # time.time() of arrival
+
+
+@dataclass(slots=True, kw_only=True)
+class Intake:
+    """Bounded wakeup buffer; overflow is flagged, never blocks the producer."""
+
+    maxsize: int
+    queue: asyncio.Queue[Wakeup] = field(init=False, repr=False)
+    overflowed: bool = field(init=False, default=False)
+
+    def __post_init__(self) -> None:
+        self.queue = asyncio.Queue(maxsize=self.maxsize)
+
+    def push(self, payload: str) -> None:
+        try:
+            self.queue.put_nowait(Wakeup(payload=payload, at=time.time()))
+        except asyncio.QueueFull:
+            self.overflowed = True
+
+    async def get(self) -> Wakeup:
+        return await self.queue.get()
+
+    async def get_within(self, timeout: float) -> Wakeup | None:
+        # asyncio.timeout, not wait_for: 3.11's wait_for can swallow an
+        # external cancel when the inner get() already has an item, leaving
+        # the pump task uncancellable and aclose() hanging
+        try:
+            async with asyncio.timeout(timeout):
+                return await self.queue.get()
+        except TimeoutError:
+            return None
+
+    def consume_overflow(self) -> bool:
+        """Check-and-clear the overflow flag (set concurrently by push); drains on overflow."""
+        if self.overflowed:
+            self.overflowed = False
+            self.drain()
+            return True
+        return False
+
+    def drain(self) -> None:
+        while True:
+            try:
+                self.queue.get_nowait()
+            except asyncio.QueueEmpty:
+                return
+
+
+@dataclass(slots=True)
+class Coalescer:
+    """Dedup buffer: one ``Event`` per payload, counting arrivals."""
+
+    pending: dict[str, Event] = field(init=False, default_factory=dict)
+
+    def add(self, wakeup: Wakeup) -> None:
+        prev = self.pending.get(wakeup.payload)
+        if prev is None:
+            self.pending[wakeup.payload] = Event(payload=wakeup.payload, first_seen=wakeup.at)
+        else:
+            self.pending[wakeup.payload] = Event(
+                payload=prev.payload, first_seen=prev.first_seen, count=prev.count + 1
+            )
+
+    def flush(self) -> Batch:
+        """Return the buffered window as a ``Batch`` and reset."""
+        batch = Batch(tuple(self.pending.values()))
+        self.pending.clear()
+        return batch
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Debouncer:
+    """Window policy: rolling ``debounce`` quiet period, hard-capped at ``max_batch_wait``."""
+
+    debounce: float
+    max_batch_wait: float
+
+    async def next_item(self, intake: Intake) -> FeedItem:
+        """Collect one window from ``intake``; overflow yields ``Resync("overflow")``."""
+        wakeup = await intake.get()
+        if intake.consume_overflow():
+            return Resync("overflow")
+
+        coalescer = Coalescer()
+        coalescer.add(wakeup)
+        hard_deadline = time.monotonic() + self.max_batch_wait
+        while True:
+            remaining = min(self.debounce, hard_deadline - time.monotonic())
+            if remaining <= 0:
+                break
+            more = await intake.get_within(remaining)
+            if more is None:
+                break
+            coalescer.add(more)
+
+        if intake.consume_overflow():
+            return Resync("overflow")
+        return coalescer.flush()
+
+
+@dataclass(frozen=True, slots=True)
+class Backoff:
+    """Jittered exponential reconnect delay."""
+
+    initial: float = 0.1
+    maximum: float = 5.0
+
+    def delay(self, attempt: int) -> float:
+        base = min(self.maximum, self.initial * (2.0 ** min(attempt - 1, 16)))
+        return base * random.uniform(0.5, 1.5)
+
+
+@dataclass(slots=True, kw_only=True)
+class FeedService:
+    """Manages the moving parts: intake -> debouncer -> output, tasks, shutdown."""
+
+    intake: Intake
+    debouncer: Debouncer
+    failsafe: float | None = None
+    out: asyncio.Queue[FeedItem | None] = field(init=False, repr=False)  # None = closed
+    tasks: list[asyncio.Task[None]] = field(init=False, default_factory=list)
+    started: bool = field(init=False, default=False)
+    closing: bool = field(init=False, default=False)
+
+    def __post_init__(self) -> None:
+        self.out = asyncio.Queue()
+
+    # -- transport side --
+
+    def push(self, payload: str) -> None:
+        self.intake.push(payload)
+
+    def emit(self, item: FeedItem) -> None:
+        self.out.put_nowait(item)
+
+    # -- lifecycle --
+
+    def start(self, supervisor: Callable[[], Coroutine[None, None, None]], name: str) -> None:
+        if self.started:
+            return
+        self.started = True
+        self.tasks.append(asyncio.create_task(supervisor(), name=f"{name}-supervisor"))
+        self.tasks.append(asyncio.create_task(self._pump(), name=f"{name}-pump"))
+        if self.failsafe is not None:
+            self.tasks.append(asyncio.create_task(self._failsafe_loop(self.failsafe), name=f"{name}-failsafe"))
+
+    async def aclose(self) -> None:
+        if self.closing:
+            return
+        self.closing = True
+        for t in self.tasks:
+            t.cancel()
+        for t in self.tasks:
+            with contextlib.suppress(asyncio.CancelledError):
+                await t
+        self.out.put_nowait(None)
+
+    # -- consumer side --
+
+    async def next_item(self) -> FeedItem | None:
+        """Next item, or ``None`` once closed."""
+        return await self.out.get()
+
+    # -- internal loops --
+
+    async def _pump(self) -> None:
+        while True:
+            self.emit(await self.debouncer.next_item(self.intake))
+
+    async def _failsafe_loop(self, interval: float) -> None:
+        while True:
+            await asyncio.sleep(interval)
+            self.emit(Resync("failsafe"))
+
+
+class BaseFeed:
+    """Async-iterator surface over a ``FeedService``; subclasses provide the transport.
+
+    Subclasses implement ``_supervisor`` (call ``_emit_resync`` per
+    (re)connect, ``_push_raw`` per wakeup) and may override ``_extra_close``.
+    """
+
+    def __init__(
+        self,
+        *,
+        debounce: float = 0.05,
+        max_batch_wait: float | None = None,
+        failsafe: float | None = None,
+        backoff: tuple[float, float] = (0.1, 5.0),
+        raw_queue_size: int = 8192,
+    ) -> None:
+        self._service = FeedService(
+            intake=Intake(maxsize=raw_queue_size),
+            debouncer=Debouncer(
+                debounce=debounce,
+                max_batch_wait=max_batch_wait if max_batch_wait is not None else debounce * 20,
+            ),
+            failsafe=failsafe,
+        )
+        self._backoff = Backoff(initial=backoff[0], maximum=backoff[1])
+        self.connection_pid: int | None = None  # server backend pid while connected
+
+    # -- lifecycle --
+
+    async def __aenter__(self) -> Self:
+        self._ensure_started()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    def _ensure_started(self) -> None:
+        self._service.start(self._supervisor, name=type(self).__name__)
+
+    async def aclose(self) -> None:
+        if self._service.closing:
+            return
+        await self._service.aclose()
+        await self._extra_close()
+        self.connection_pid = None
+
+    async def _extra_close(self) -> None:  # pragma: no cover - subclass hook
+        return
+
+    # -- consumer side --
+
+    def __aiter__(self) -> AsyncIterator[FeedItem]:
+        self._ensure_started()
+        return self
+
+    async def __anext__(self) -> FeedItem:
+        item = await self._service.next_item()
+        if item is None:
+            raise StopAsyncIteration
+        return item
+
+    # -- transport-facing helpers --
+
+    @property
+    def _closing(self) -> bool:
+        return self._service.closing
+
+    def _push_raw(self, payload: str) -> None:
+        self._service.push(payload)
+
+    def _emit_resync(self, reason: str) -> None:
+        self._service.emit(Resync(reason))
+
+    def _backoff_delay(self, attempt: int) -> float:
+        return self._backoff.delay(attempt)
+
+    async def _supervisor(self) -> None:  # pragma: no cover - abstract
+        raise NotImplementedError

pgnudge/proto.py

@@ -0,0 +1,248 @@
+"""Minimal walsender-mode protocol client, stdlib asyncio + scramp.
+
+Startup with ``replication=database``, optional TLS, trust/cleartext/SCRAM
+auth, simple query, CopyBoth streaming. See PostgreSQL docs: "Streaming
+Replication Protocol", "Message Formats".
+"""
+
+import asyncio
+import contextlib
+import ssl as ssl_module
+import struct
+import time
+from dataclasses import dataclass
+from typing import ClassVar, Self
+
+from scramp import ScramClient
+
+__all__ = ["PgServerError", "XLogData", "Keepalive", "WalsenderConnection"]
+
+
+class PgServerError(Exception):
+    """ErrorResponse from the server, with the field map preserved."""
+
+    def __init__(self, fields: dict[str, str]) -> None:
+        self.fields = fields
+        super().__init__(f"{fields.get('S', 'ERROR')} {fields.get('C', '?????')}: {fields.get('M', 'unknown')}")
+
+
+@dataclass(frozen=True, slots=True)
+class XLogData:
+    end_lsn: int
+    payload: bytes
+
+
+@dataclass(frozen=True, slots=True)
+class Keepalive:
+    end_lsn: int
+    reply_requested: bool
+
+
+def _parse_error(body: bytes) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    i = 0
+    while i < len(body) and body[i : i + 1] != b"\x00":
+        code = chr(body[i])
+        j = body.index(b"\x00", i + 1)
+        fields[code] = body[i + 1 : j].decode("utf-8", "replace")
+        i = j + 1
+    return fields
+
+
+def _default_ssl_context() -> ssl_module.SSLContext:
+    ctx = ssl_module.create_default_context()
+    # Azure/managed endpoints commonly need verify-full with the platform CA
+    # bundle, which create_default_context gives you. For self-signed dev
+    # servers pass your own context with CERT_NONE.
+    return ctx
+
+
+class WalsenderConnection:
+    """One logical-replication walsender session."""
+
+    _PROTOCOL_V3: ClassVar[int] = 196608
+    _SSL_REQUEST: ClassVar[int] = 80877103
+    _PG_EPOCH_UNIX: ClassVar[int] = 946_684_800  # 2000-01-01 00:00:00 UTC
+
+    def __init__(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter, *, tls: bool = False
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+        self.tls = tls
+        self.backend_pid: int | None = None
+
+    # -- connection & auth ----------------------------------------------------
+
+    @classmethod
+    async def connect(
+        cls,
+        *,
+        host: str,
+        port: int,
+        user: str,
+        database: str,
+        password: str | None = None,
+        ssl: bool | ssl_module.SSLContext = False,
+        application_name: str = "pgnudge",
+        connect_timeout: float = 10.0,
+    ) -> Self:
+        reader, writer = await asyncio.wait_for(asyncio.open_connection(host, port), connect_timeout)
+        if ssl:
+            writer.write(struct.pack("!ii", 8, cls._SSL_REQUEST))
+            await writer.drain()
+            answer = await reader.readexactly(1)
+            if answer != b"S":
+                writer.close()
+                raise ConnectionError("server refused SSL")
+            ctx = ssl if isinstance(ssl, ssl_module.SSLContext) else _default_ssl_context()
+            await writer.start_tls(ctx, server_hostname=host)
+        conn = cls(reader, writer, tls=bool(ssl))
+        try:
+            await asyncio.wait_for(
+                conn._startup(user=user, database=database, password=password, application_name=application_name),
+                connect_timeout,
+            )
+        except BaseException:
+            conn.abort()
+            raise
+        return conn
+
+    async def _startup(self, *, user: str, database: str, password: str | None, application_name: str) -> None:
+        params = {
+            "user": user,
+            "database": database,
+            "replication": "database",
+            "application_name": application_name,
+            "client_encoding": "UTF8",
+        }
+        body = b"".join(k.encode() + b"\x00" + v.encode() + b"\x00" for k, v in params.items()) + b"\x00"
+        self._writer.write(struct.pack("!ii", 8 + len(body), self._PROTOCOL_V3) + body)
+        await self._writer.drain()
+
+        scram: ScramClient | None = None
+        while True:
+            mtype, mbody = await self._read_message()
+            if mtype == b"R":
+                (code,) = struct.unpack("!i", mbody[:4])
+                if code == 0:  # AuthenticationOk
+                    break
+                if code == 3:  # CleartextPassword
+                    if not self.tls:
+                        raise PgServerError(
+                            {
+                                "M": "refusing cleartext password on an unencrypted connection; "
+                                "enable ssl= or use SCRAM-SHA-256"
+                            }
+                        )
+                    if password is None:
+                        raise PgServerError({"M": "server requested a password but none was given"})
+                    self._write_message(b"p", password.encode() + b"\x00")
+                    await self._writer.drain()
+                elif code == 10:  # SASL
+                    mechanisms = [m.decode() for m in mbody[4:].split(b"\x00") if m]
+                    plain = [m for m in mechanisms if not m.endswith("-PLUS")]
+                    if not plain or password is None:
+                        raise PgServerError({"M": f"unsupported SASL mechanisms {mechanisms} or missing password"})
+                    scram = ScramClient(plain, user, password)
+                    first = scram.get_client_first().encode()
+                    self._write_message(b"p", scram.mechanism_name.encode() + b"\x00" + struct.pack("!i", len(first)) + first)
+                    await self._writer.drain()
+                elif code == 11:  # SASLContinue
+                    assert scram is not None
+                    scram.set_server_first(mbody[4:].decode())
+                    self._write_message(b"p", scram.get_client_final().encode())
+                    await self._writer.drain()
+                elif code == 12:  # SASLFinal
+                    assert scram is not None
+                    scram.set_server_final(mbody[4:].decode())
+                else:
+                    raise PgServerError({"M": f"unsupported authentication request (code {code}); pgnudge speaks trust, cleartext and SCRAM-SHA-256"})
+            elif mtype == b"E":
+                raise PgServerError(_parse_error(mbody))
+            else:  # NoticeResponse etc.
+                continue
+
+        while True:  # post-auth: BackendKeyData / ReadyForQuery ('S' ParameterStatus skipped)
+            mtype, mbody = await self._read_message()
+            if mtype == b"K":
+                self.backend_pid = struct.unpack("!i", mbody[:4])[0]
+            elif mtype == b"Z":
+                return
+            elif mtype == b"E":
+                raise PgServerError(_parse_error(mbody))
+
+    # -- framing ---------------------------------------------------------------
+
+    async def _read_message(self) -> tuple[bytes, bytes]:
+        header = await self._reader.readexactly(5)
+        mtype = header[:1]
+        (length,) = struct.unpack("!i", header[1:5])
+        body = await self._reader.readexactly(length - 4)
+        return mtype, body
+
+    def _write_message(self, mtype: bytes, body: bytes) -> None:
+        self._writer.write(mtype + struct.pack("!i", 4 + len(body)) + body)
+
+    # -- simple query (the only subprotocol walsender mode speaks) --------------
+
+    async def simple_query(self, sql: str) -> None:
+        """Run a command and drain to ReadyForQuery; result rows are ignored."""
+        self._write_message(b"Q", sql.encode() + b"\x00")
+        await self._writer.drain()
+        error: dict[str, str] | None = None
+        while True:
+            mtype, mbody = await self._read_message()
+            if mtype == b"E":
+                error = _parse_error(mbody)
+            elif mtype == b"Z":
+                if error is not None:
+                    raise PgServerError(error)
+                return
+            # 'T' RowDescription, 'D' DataRow, 'C' CommandComplete, 'N' Notice: skipped
+
+    # -- CopyBoth streaming ------------------------------------------------------
+
+    async def start_replication(self, command: str) -> None:
+        """Send START_REPLICATION and consume up to CopyBothResponse."""
+        self._write_message(b"Q", command.encode() + b"\x00")
+        await self._writer.drain()
+        while True:
+            mtype, mbody = await self._read_message()
+            if mtype == b"W":
+                return
+            if mtype == b"E":
+                raise PgServerError(_parse_error(mbody))
+
+    async def read_stream(self) -> XLogData | Keepalive:
+        """Read the next replication message. Raises on stream end or error."""
+        while True:
+            mtype, mbody = await self._read_message()
+            if mtype == b"d":
+                kind = mbody[:1]
+                if kind == b"w":
+                    _start, end, _ts = struct.unpack("!QQQ", mbody[1:25])
+                    return XLogData(end_lsn=end, payload=mbody[25:])
+                if kind == b"k":
+                    end, _ts, reply = struct.unpack("!QQB", mbody[1:18])
+                    return Keepalive(end_lsn=end, reply_requested=bool(reply))
+                continue  # unknown CopyData subtype
+            if mtype == b"E":
+                raise PgServerError(_parse_error(mbody))
+            if mtype in (b"c", b"C", b"Z"):
+                raise ConnectionResetError("replication stream ended")
+
+    async def send_standby_status(self, lsn: int, *, reply: bool = False) -> None:
+        """Acknowledge everything up to ``lsn``; ``reply`` asks the server to answer with a keepalive."""
+        ts = int((time.time() - self._PG_EPOCH_UNIX) * 1_000_000)
+        self._write_message(b"d", b"r" + struct.pack("!QQQQB", lsn, lsn, lsn, ts, int(reply)))
+        await self._writer.drain()
+
+    # -- teardown ----------------------------------------------------------------
+
+    def abort(self) -> None:
+        """Hard-close the socket, no protocol goodbye — slot cleanup must survive crashes."""
+        with contextlib.suppress(Exception):
+            transport = self._writer.transport
+            if isinstance(transport, asyncio.WriteTransport):
+                transport.abort()

pgnudge/wal.py

@@ -0,0 +1,229 @@
+"""WalFeed: logical decoding from a TEMPORARY replication slot.
+
+The slot auto-drops when the session ends, cleanly or not — nothing pgnudge
+creates outlives the connection. From-connect-only: a fresh slot per
+(re)connect, no history, no backfill. Semantics and the gap-free handshake
+argument: README. Server needs ``wal_level=logical``, a REPLICATION role,
+and an output plugin (wal2json or test_decoding).
+"""
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import re
+import secrets
+import ssl as ssl_module
+import time
+from typing import ClassVar
+
+from pgnudge.engine import BaseFeed
+from pgnudge.proto import WalsenderConnection, XLogData
+
+__all__ = ["WalFeed"]
+
+
+def _quote_value(v: str) -> str:
+    return "'" + v.replace("'", "''") + "'"
+
+
+class WalFeed(BaseFeed):
+    """Async-iterable ``Resync | Batch`` feed from a temporary logical slot.
+
+    Payloads are ``schema.table``. ``tables`` filters server-side (wal2json
+    only); ``ssl`` takes True or an ``ssl.SSLContext``; ``status_interval``
+    must stay under the server's ``wal_sender_timeout`` (default 60 s).
+    ``liveness_timeout`` (must exceed ``status_interval``; None disables)
+    bounds how long the feed tolerates a silent server before reconnecting.
+    """
+
+    log: ClassVar[logging.Logger] = logging.getLogger("pgnudge.wal")
+
+    _TEST_DECODING_RE: ClassVar[re.Pattern[str]] = re.compile(
+        r"^table (.+?): (?:INSERT|UPDATE|DELETE|TRUNCATE)"
+    )
+
+    def __init__(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 5432,
+        user: str,
+        database: str,
+        password: str | None = None,
+        ssl: bool | ssl_module.SSLContext = False,
+        tables: list[str] | None = None,
+        plugin: str = "wal2json",
+        application_name: str = "pgnudge",
+        status_interval: float = 10.0,
+        liveness_timeout: float | None = 30.0,
+        connect_timeout: float = 10.0,
+        debounce: float = 0.05,
+        max_batch_wait: float | None = None,
+        failsafe: float | None = None,
+        backoff: tuple[float, float] = (0.1, 5.0),
+        raw_queue_size: int = 8192,
+    ) -> None:
+        super().__init__(
+            debounce=debounce,
+            max_batch_wait=max_batch_wait,
+            failsafe=failsafe,
+            backoff=backoff,
+            raw_queue_size=raw_queue_size,
+        )
+        if plugin not in ("wal2json", "test_decoding"):
+            raise ValueError(f"unsupported plugin {plugin!r}")
+        self._host = host
+        self._port = port
+        self._user = user
+        self._database = database
+        self._password = password
+        self._ssl = ssl
+        self._tables = list(tables) if tables else None
+        self._plugin = plugin
+        self._application_name = application_name
+        self._status_interval = status_interval
+        self.liveness_timeout = liveness_timeout
+        self._connect_timeout = connect_timeout
+
+        self._conn: WalsenderConnection | None = None
+        self._last_lsn = 0
+        self.last_inbound = time.monotonic()
+        self.slot_name: str | None = None
+
+    # -- payload parsing ----------------------------------------------------------
+
+    @staticmethod
+    def _parse_wal2json_v2(payload: bytes) -> list[str]:
+        try:
+            obj: object = json.loads(payload)
+        except ValueError:
+            return []
+        if isinstance(obj, dict) and obj.get("action") in ("I", "U", "D", "T"):
+            return [f"{obj.get('schema', '?')}.{obj.get('table', '?')}"]
+        return []
+
+    @classmethod
+    def _parse_test_decoding(cls, payload: bytes) -> list[str]:
+        # TRUNCATE lists every affected table on one line, ", "-joined
+        m = cls._TEST_DECODING_RE.match(payload.decode("utf-8", "replace"))
+        return m.group(1).split(", ") if m else []
+
+    # -- teardown ---------------------------------------------------------------
+
+    async def _extra_close(self) -> None:
+        # Hard-close on purpose, no DROP: crash and clean exit must exercise
+        # the same server-side cleanup path.
+        if self._conn is not None:
+            self._conn.abort()
+            self._conn = None
+        self.slot_name = None
+
+    # -- replication command assembly --------------------------------------------
+
+    def _plugin_options(self) -> str:
+        if self._plugin == "wal2json":
+            opts = [('"format-version"', "2"), ('"include-transaction"', "false")]
+            if self._tables:
+                opts.append(('"add-tables"', ",".join(self._tables)))
+            return ", ".join(f"{name} {_quote_value(value)}" for name, value in opts)
+        return '"skip-empty-xacts" \'1\''
+
+    # -- supervisor ---------------------------------------------------------------
+
+    async def _supervisor(self) -> None:
+        parse = self._parse_wal2json_v2 if self._plugin == "wal2json" else self._parse_test_decoding
+        attempt = 0
+        first = True
+        while not self._closing:
+            try:
+                conn = await WalsenderConnection.connect(
+                    host=self._host,
+                    port=self._port,
+                    user=self._user,
+                    database=self._database,
+                    password=self._password,
+                    ssl=self._ssl,
+                    application_name=self._application_name,
+                    connect_timeout=self._connect_timeout,
+                )
+            except Exception as exc:
+                self.log.warning("connect to %s:%d failed: %s", self._host, self._port, exc)
+                attempt += 1
+                delay = self._backoff_delay(attempt)
+                self.log.debug("reconnect attempt %d in %.2fs", attempt, delay)
+                await asyncio.sleep(delay)
+                continue
+
+            self._conn = conn
+            self.connection_pid = conn.backend_pid
+            slot = f"pgnudge_{os.getpid()}_{secrets.token_hex(3)}"
+            feedback: asyncio.Task[None] | None = None
+            try:
+                await conn.simple_query(
+                    # SNAPSHOT 'nothing': from-connect-only, the Resync refetch is the backfill
+                    f'CREATE_REPLICATION_SLOT "{slot}" TEMPORARY LOGICAL {self._plugin} (SNAPSHOT \'nothing\')'
+                )
+                await conn.start_replication(
+                    f'START_REPLICATION SLOT "{slot}" LOGICAL 0/0 ({self._plugin_options()})'
+                )
+                self.slot_name = slot
+                attempt = 0
+                self._emit_resync("connected" if first else "reconnected")
+                self.log.info("streaming from slot %s (backend pid %s)", slot, conn.backend_pid)
+                first = False
+
+                self._last_lsn = 0
+                self.last_inbound = time.monotonic()
+                feedback = asyncio.create_task(self._feedback_loop(conn))
+                while True:
+                    msg = await conn.read_stream()
+                    self.last_inbound = time.monotonic()
+                    if isinstance(msg, XLogData):
+                        self._last_lsn = max(self._last_lsn, msg.end_lsn)
+                        for table in parse(msg.payload):
+                            self._push_raw(table)
+                    else:  # Keepalive — read_stream returns nothing else
+                        self._last_lsn = max(self._last_lsn, msg.end_lsn)
+                        if msg.reply_requested:
+                            await conn.send_standby_status(self._last_lsn)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                # fall through to reconnect with a fresh slot
+                self.log.warning("stream error on slot %s, reconnecting: %s", slot, exc)
+            finally:
+                if feedback is not None:
+                    feedback.cancel()
+                    with contextlib.suppress(asyncio.CancelledError):
+                        await feedback
+                self.connection_pid = None
+                self.slot_name = None
+                self._conn = None
+                conn.abort()
+
+            if not self._closing:
+                attempt += 1
+                delay = self._backoff_delay(attempt)
+                self.log.debug("reconnect attempt %d in %.2fs", attempt, delay)
+                await asyncio.sleep(delay)
+
+    async def _feedback_loop(self, conn: WalsenderConnection) -> None:
+        # With liveness on, every status requests a keepalive back, so a
+        # healthy connection has inbound traffic every status_interval and
+        # silence beyond liveness_timeout means the link or walsender is
+        # dead. abort() breaks the supervisor's blocked read -> reconnect.
+        probe = self.liveness_timeout is not None
+        while True:
+            await asyncio.sleep(self._status_interval)
+            idle = time.monotonic() - self.last_inbound
+            if self.liveness_timeout is not None and idle > self.liveness_timeout:
+                self.log.warning("no server traffic for %.1fs; aborting connection", idle)
+                conn.abort()
+                return
+            try:
+                await conn.send_standby_status(self._last_lsn, reply=probe)
+            except Exception as exc:
+                self.log.debug("standby status send failed: %s", exc)
+                return

pgnudge-1.0.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: pgnudge
+Version: 1.0.0
+Summary: Push-only change nudges from PostgreSQL logical replication: the database nudges, consumers refetch.
+Project-URL: Homepage, https://github.com/janbjorge/pgnudge
+License: MIT
+License-File: LICENSE
+Keywords: asyncio,cache-invalidation,change-feed,logical-replication,postgresql
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.11
+Requires-Dist: scramp>=1.4
+Description-Content-Type: text/markdown
+
+# pgnudge
+
+**Push-only change nudges from PostgreSQL — nothing left behind on the server.**
+
+[![CI](https://github.com/janbjorge/pgnudge/actions/workflows/ci.yml/badge.svg)](https://github.com/janbjorge/pgnudge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pgnudge)](https://pypi.org/project/pgnudge/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/pgnudge/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Your database moves; your app wakes up. pgnudge tells you *that* something
+changed and *which tables* — you already know how to load the data. Built
+for live read models: dashboards, cache invalidation, anything that
+renders a query and wants to re-render the instant the database moves.
+
+```
+pip install pgnudge
+```
+
+Python ≥ 3.11, PostgreSQL ≥ 16. One dependency:
+[scramp](https://github.com/tlocke/scramp) (pure-Python SCRAM auth). No
+database driver — pgnudge speaks the PostgreSQL replication protocol
+itself.
+
+## Sixty-second tour
+
+```python
+from pgnudge import Batch, Resync, WalFeed
+
+async with WalFeed(
+    host="db.example.com", user="wal_user", password=...,
+    database="app", ssl=True,
+    tables=["public.orders", "public.stations"],   # server-side filter
+    debounce=0.05,
+) as feed:
+    async for item in feed:
+        match item:
+            case Resync():           # connected / reconnected / overflow / failsafe
+                await reload_everything()
+            case Batch(events=evs):  # coalesced wakeups: which tables moved
+                await reload(tables={e.payload for e in evs})
+```
+
+There is no step 1. Nothing to install in the database, nothing to migrate,
+nothing to revert. Close the connection and the server forgets pgnudge ever
+existed.
+
+## The guarantee
+
+`WalFeed` creates **nothing on the server that outlives the connection.**
+
+```
+your app ──── async for item in feed ────▶ Resync | Batch
+  ▲
+  │  walsender protocol (TLS, SCRAM-SHA-256, CopyBoth) — no driver
+  │
+PostgreSQL ── TEMPORARY replication slot ── logical decoding
+              └── dropped by the server the instant the session ends,
+                  cleanly or not
+```
+
+The temporary replication slot is the only primitive in PostgreSQL that
+gives you a change feed with connection-scoped lifetime: the server is
+contractually obliged to drop it the moment the session ends — cleanly, by
+crash, by `kill -9`, by yanked cable, by `pg_terminate_backend`. No
+triggers, no functions, no catalog objects, no persistent slots, no cleanup
+jobs. The test suite ends by hard-aborting the socket with no protocol
+goodbye and asserting `pg_replication_slots` is empty.
+
+What *is* required is PostgreSQL 16+ and one-time server **configuration**
+(settings, not objects — nothing accumulates): `wal_level = logical`, a
+role with `REPLICATION`, and an output plugin — `wal2json` (default;
+preinstalled on Azure Flexible Server, RDS, and most managed platforms) or
+`test_decoding` (ships inside PostgreSQL itself).
+
+The full mechanics — logical decoding, temporary-slot semantics, the
+gap-free handshake argument, and **when not to use pgnudge** — are in
+[docs/temporary-slots.md](docs/temporary-slots.md).
+
+## The contract
+
+A feed yields exactly two item types:
+
+- **`Resync(reason)`** — reload everything. Emitted on every connect and
+  reconnect, on internal queue overflow, and (optionally) on a failsafe
+  interval. Handle `Resync` correctly and nothing can make your view wrong.
+- **`Batch(events)`** — one debounce window's worth of wakeups,
+  deduplicated, in arrival order. Each `Event` carries `payload`
+  (`schema.table` — the stable v1 payload contract), `first_seen`, `count`.
+
+**Delivery is at-least-once wakeups, from the point of connect only.**
+Events are hints to refetch, never facts to apply. There is no history and
+no backfill, by design and by mechanism: the slot is created fresh at every
+(re)connect with `SNAPSHOT 'nothing'`, and a logical slot can only decode
+forward from its creation point. The handshake is gap-free — `Resync` is
+emitted only after the stream is live, so the refetch it triggers observes
+a state at or after the slot's start point, and every later commit produces
+a nudge; anything landing in between is simply covered twice, which
+at-least-once absorbs. On reconnect `WalFeed` resyncs rather than resumes.
+No replay, no exactly-once, no row images, *on purpose*: refetching is
+idempotent and you have a database right there. (One nuance: slot creation
+waits for write transactions in flight at connect time, so a long-running
+write delays connect — it never causes history to be delivered.)
+
+**Coalescing:** per-row changes within the debounce window collapse
+client-side into one `Event` with a `count` — a 500-row transaction on one
+table is one `Event`, `count=500`, one wakeup, one refetch.
+
+`INSERT`, `UPDATE`, `DELETE`, and `TRUNCATE` all nudge. Logical decoding
+does not carry other DDL, so schema changes don't — pair migrations with a
+refetch if your view depends on them.
+
+## Why not LISTEN/NOTIFY?
+
+`NOTIFY` doesn't fire itself: making it track data changes means triggers,
+and triggers are persistent catalog objects — schema footprint, migration
+reviews, cleanup jobs, drift. pgnudge's whole premise is refusing that
+trade. Logical decoding gets the same wakeups straight from the WAL with
+zero objects. (LISTEN is still great on the *consuming* side — see Fan-out.)
+
+## Fan-out
+
+One `WalFeed` per process is the normal shape. For many consumers, run one
+`WalFeed` in a small bridge daemon that republishes to a NOTIFY channel via
+`pg_notify`, and let consumers attach with plain LISTEN (any driver —
+LISTEN is session state, zero objects). One REPLICATION grant total, one
+decoding pass total, and still zero persistent server objects: the bridge's
+temp slot dies with the bridge.
+
+## Ops notes
+
+- `status_interval` (default 10 s) must stay under the server's
+  `wal_sender_timeout` (default 60 s); the feed also answers
+  reply-requested keepalives immediately.
+- `liveness_timeout` (default 30 s, must exceed `status_interval`,
+  `None` disables): each status report asks the server to answer with a
+  keepalive, so a healthy connection always has inbound traffic — silence
+  longer than the timeout means a dead link (NAT drop, yanked VPN, hung
+  walsender) and the feed aborts and reconnects instead of blocking
+  forever.
+- While connected, each `WalFeed` holds one replication slot and one WAL
+  sender against `max_replication_slots` / `max_wal_senders`. Disconnected
+  feeds hold nothing — that's the point — which also means an idle feed
+  never retains WAL.
+- Managed platforms: enabling `wal_level=logical` typically requires a
+  restart (once); grant `REPLICATION` to a dedicated role rather than
+  widening an app role — logical decoding sees the whole database's stream.
+- Thundering herd: a database restart reconnects every feed at once, and
+  every consumer's `Resync` handler refetches at once. Reconnect timing is
+  already jittered, but the refetch is your code — add jitter there when
+  many consumers share a database, or fan out through the bridge daemon so
+  a single process refetches per change.
+- TLS: `ssl=True` uses platform CA verification; pass an `ssl.SSLContext`
+  for custom trust. SCRAM-SHA-256 is supported everywhere; cleartext auth
+  only over TLS — pgnudge refuses to send a password on an unencrypted
+  connection.
+- Logging: the `pgnudge.wal` logger (stdlib `logging`, no handlers
+  configured by the library) reports connect failures and stream errors at
+  WARNING, successful (re)connects at INFO, and backoff timing at DEBUG —
+  a feed that reconnects in a loop is visible, not silent.
+
+## Tested how
+
+The suite spins up real PostgreSQL via testcontainers (nothing to install
+beyond Docker) and proves the claims live: no backfill of pre-connect
+writes, client-side coalescing (50-row txn → one `Event`, `count=50`),
+reconnect gets a fresh slot with the old one auto-dropped, TLS + SCRAM over
+an encrypted stream, and the flagship — hard socket abort with no protocol
+goodbye leaves `pg_replication_slots` empty.
+
+```bash
+uv sync && uv run pytest
+```
+
+## Non-goals
+
+- **Not a queue.** No durability, no competing consumers, no retries. If a
+  message must be processed, use a job queue
+  (e.g. [pgqueuer](https://github.com/janbjorge/pgqueuer)) — pgnudge is its
+  broadcast-shaped sibling: pgqueuer moves *work*, pgnudge moves
+  *wakefulness*.
+- **Not CDC.** No row images, no before/after, no replay. Refetch.
+- **Not a driver.** The protocol client implements exactly what a
+  logical-decoding consumer needs: startup, auth, simple query, CopyBoth.
+
+## Roadmap
+
+- Native `pgoutput` parsing would drop the wal2json server-plugin
+  requirement — but pgoutput only decodes through a *publication*, and a
+  publication is a persistent catalog object, in direct tension with the
+  nothing-outlives-the-connection guarantee. Conditional at best: viable
+  only if a pre-existing, application-owned publication counts as
+  configuration rather than footprint.
+- Opt-in `schema.table:pk` payloads for sharper client-side routing.
+- The bridge daemon as a first-class artifact — same feed contract, one
+  slot fanned out over NOTIFY; a native (Zig) implementation is the
+  intended long-term core.
+
+MIT licensed.

pgnudge-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pgnudge/__init__.py,sha256=zeH6zY3i-CC0TNDQ2C502xmZRvcut3xQqXBwUs5i1Dc,372
+pgnudge/core.py,sha256=Fh2AaK2s8ghnV-CV_XoKRCrFAtw9AOq9NO-LhnVBHyI,1012
+pgnudge/engine.py,sha256=t8k2hooTtzVMc-lIKs9e00h88m5Fr9oiiG2azJDYiPI,9011
+pgnudge/proto.py,sha256=rybHPeccoF8O2JR8mju09xrx-DH3hmxlg3M_Wu1bhhU,10212
+pgnudge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pgnudge/wal.py,sha256=tokjQe6S4SYJkdmHxnKV8ja11gIQbNyE357QMLAojE4,9341
+pgnudge-1.0.0.dist-info/METADATA,sha256=83ULx4vjYMYgGYFPBOG_16hJvetrrljqiOxCS1YB5Cw,10252
+pgnudge-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pgnudge-1.0.0.dist-info/licenses/LICENSE,sha256=0PnG3kXuspi8WEguytXeC0Tnn9YdpV8vJlzTIeSZhC4,1077
+pgnudge-1.0.0.dist-info/RECORD,,

pgnudge-1.0.0.dist-info/WHEEL

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

pgnudge-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pgnudge contributors
+
+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.