sillo-wire 0.1.0.dev1__py3-none-any.whl

sillo_wire/hub.py

@@ -0,0 +1,315 @@
+"""Rooms, membership and fan-out.
+
+A :class:`Hub` owns rooms and the peers in them. It is an ordinary object, not
+a module of class methods over a global dict, so two hubs are two independent
+worlds: a test gets a fresh one per case instead of remembering to flush shared
+state, and an application that serves several tenants can keep their traffic
+apart without a naming convention.
+
+Fan-out is concurrent and non-blocking. Delivering to a room enqueues on every
+peer at once and returns a :class:`~sillo_wire.envelope.DeliveryReport`; it
+never waits on a socket, so one client that has stopped reading cannot hold up
+the rest of the room.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import typing
+
+from sillo_wire.backlog import Backlog, MemoryBacklog
+from sillo_wire.envelope import DeliveryReport, Envelope
+from sillo_wire.errors import RoomNotFound
+from sillo_wire.peer import Peer
+
+__all__ = ["Hub"]
+
+#: Called as ``listener(room, peer)`` when membership changes. Sync or async.
+PresenceListener = typing.Callable[[str, Peer], typing.Any]
+
+
+class Hub:
+    """A set of rooms and the peers subscribed to them.
+
+    Args:
+        backlog: Where delivered envelopes are retained for replay. Defaults to
+            an in-memory one; pass :class:`~sillo_wire.backlog.NullBacklog` to
+            keep nothing.
+    """
+
+    __slots__ = ("_backlog", "_on_join", "_on_leave", "_rooms")
+
+    def __init__(self, backlog: Backlog | None = None) -> None:
+        self._rooms: dict[str, set[Peer]] = {}
+        self._backlog: Backlog = MemoryBacklog() if backlog is None else backlog
+        self._on_join: list[PresenceListener] = []
+        self._on_leave: list[PresenceListener] = []
+
+    # ── membership ───────────────────────────────────────────────────────
+
+    async def join(self, peer: Peer, room: str) -> bool:
+        """Subscribe *peer* to *room*. Returns whether it was newly added.
+
+        Starts the peer's writer if it is not already running, so a caller
+        never has to remember to.
+        """
+        if not room:
+            raise ValueError("room name must not be empty")
+
+        members = self._rooms.setdefault(room, set())
+        if peer in members:
+            return False
+
+        members.add(peer)
+        peer.start()
+        await self._announce(self._on_join, room, peer)
+        return True
+
+    async def leave(self, peer: Peer, room: str) -> bool:
+        """Unsubscribe *peer* from *room*. Returns whether it was a member.
+
+        Leaving a room that does not exist, or that the peer is not in, is not
+        an error — a disconnect racing a cleanup produces both, routinely.
+        """
+        members = self._rooms.get(room)
+        if members is None or peer not in members:
+            return False
+
+        members.discard(peer)
+        if not members:
+            del self._rooms[room]
+        await self._announce(self._on_leave, room, peer)
+        return True
+
+    async def leave_all(self, peer: Peer) -> list[str]:
+        """Remove *peer* from every room. Returns the rooms it was in."""
+        left = [room for room, members in self._rooms.items() if peer in members]
+        for room in left:
+            await self.leave(peer, room)
+        return left
+
+    async def disconnect(self, peer: Peer) -> None:
+        """Remove *peer* from every room and close its socket.
+
+        The one call a consumer's disconnect path needs.
+        """
+        await self.leave_all(peer)
+        await peer.close()
+
+    # ── delivery ─────────────────────────────────────────────────────────
+
+    async def broadcast(
+        self,
+        room: str,
+        payload: typing.Any,
+        *,
+        retain: bool = True,
+    ) -> DeliveryReport:
+        """Deliver *payload* to every peer in *room*.
+
+        Args:
+            room: Which room to deliver to. An unknown room is an empty report,
+                not an error — rooms come and go with their last member.
+            payload: What to send.
+            retain: Whether to record the envelope in the backlog for replay.
+
+        Returns:
+            What happened, per peer.
+        """
+        envelope = Envelope(payload=payload, room=room)
+        if retain:
+            await self._backlog.append(envelope)
+
+        members = self._rooms.get(room)
+        if not members:
+            return DeliveryReport()
+
+        report, stale = self._offer_all(members, envelope)
+        if stale:
+            members.difference_update(stale)
+            if not members:
+                del self._rooms[room]
+        return report
+
+    async def send_to(
+        self, identity: typing.Any, payload: typing.Any
+    ) -> DeliveryReport:
+        """Deliver *payload* to every peer carrying *identity*.
+
+        This is the "reach that user wherever they are" call — one person with
+        a phone and two tabs is three peers, and all three get it. Nothing is
+        retained: the message is addressed to a person, not to a room, so there
+        is no room whose history it belongs in.
+        """
+        targets = {
+            peer
+            for members in self._rooms.values()
+            for peer in members
+            if peer.identity == identity
+        }
+        if not targets:
+            return DeliveryReport()
+        # Stale peers are not evicted here: a peer reached by identity may be
+        # in several rooms, and removing it from all of them is `prune`'s job.
+        report, _ = self._offer_all(targets, Envelope(payload=payload))
+        return report
+
+    def _offer_all(
+        self,
+        peers: typing.Iterable[Peer],
+        envelope: Envelope,
+    ) -> tuple[DeliveryReport, list[Peer]]:
+        """Enqueue *envelope* on each peer; report the outcome and the dead.
+
+        Synchronous on purpose. ``offer`` cannot block, so there is nothing to
+        await and no window in which the room's membership could change
+        underneath the loop — which is why the caller can act on the returned
+        stale list against the very set it passed in.
+        """
+        delivered = dropped = failed = 0
+        stale: list[Peer] = []
+
+        for peer in list(peers):
+            if peer.closed:
+                failed += 1
+                stale.append(peer)
+            elif peer.offer(envelope):
+                delivered += 1
+            else:
+                dropped += 1
+                # An overflow policy of CLOSE marks the peer closed as it
+                # refuses the message, so it is evictable in the same pass.
+                if peer.closed:
+                    stale.append(peer)
+
+        report = DeliveryReport(delivered=delivered, dropped=dropped, failed=failed)
+        return report, stale
+
+    # ── replay ───────────────────────────────────────────────────────────
+
+    async def replay(
+        self,
+        peer: Peer,
+        room: str,
+        *,
+        since: int = 0,
+        limit: int | None = None,
+    ) -> int:
+        """Send *peer* what it missed in *room*. Returns how many were sent.
+
+        The cursor a client sends back after reconnecting is the ``seq`` of the
+        last envelope it saw, which is why sequences are monotonic and never
+        reused.
+        """
+        missed = await self._backlog.since(room, since)
+        if limit is not None:
+            missed = missed[-limit:] if limit > 0 else []
+
+        sent = 0
+        for envelope in missed:
+            if peer.offer(envelope):
+                sent += 1
+        return sent
+
+    async def history(self, room: str, limit: int = 50) -> list[Envelope]:
+        """The most recent envelopes retained for *room*."""
+        return await self._backlog.latest(room, limit=limit)
+
+    async def clear_history(self, room: str | None = None) -> None:
+        """Forget *room*'s backlog, or every room's."""
+        await self._backlog.clear(room)
+
+    # ── presence ─────────────────────────────────────────────────────────
+
+    def on_join(self, listener: PresenceListener) -> PresenceListener:
+        """Register *listener*, called when a peer joins a room.
+
+        Returns the listener, so it works as a decorator.
+        """
+        self._on_join.append(listener)
+        return listener
+
+    def on_leave(self, listener: PresenceListener) -> PresenceListener:
+        """Register *listener*, called when a peer leaves a room."""
+        self._on_leave.append(listener)
+        return listener
+
+    async def _announce(
+        self, listeners: list[PresenceListener], room: str, peer: Peer
+    ) -> None:
+        """Run presence listeners, tolerating both sync and async ones."""
+        for listener in listeners:
+            result = listener(room, peer)
+            if inspect.isawaitable(result):
+                await result
+
+    # ── introspection ────────────────────────────────────────────────────
+
+    def rooms(self) -> list[str]:
+        """Every room with at least one peer in it."""
+        return list(self._rooms)
+
+    def members(self, room: str) -> list[Peer]:
+        """The peers in *room*, or an empty list if there is no such room."""
+        return list(self._rooms.get(room, ()))
+
+    def identities(self, room: str) -> list[typing.Any]:
+        """Distinct, non-``None`` identities present in *room*.
+
+        The presence roster: who is here, rather than how many sockets are.
+
+        Raises:
+            RoomNotFound: If *room* does not exist. Unlike a broadcast, asking
+                who is in a room that has never existed is a question with no
+                sensible empty answer — it is usually a typo.
+        """
+        if room not in self._rooms:
+            raise RoomNotFound(room)
+        seen: list[typing.Any] = []
+        for peer in self._rooms[room]:
+            if peer.identity is not None and peer.identity not in seen:
+                seen.append(peer.identity)
+        return seen
+
+    def count(self, room: str | None = None) -> int:
+        """Peers in *room*, or across every room when *room* is ``None``.
+
+        A peer in two rooms counts twice in the total, because the number being
+        reported is subscriptions rather than connections.
+        """
+        if room is not None:
+            return len(self._rooms.get(room, ()))
+        return sum(len(members) for members in self._rooms.values())
+
+    async def prune(self) -> list[Peer]:
+        """Evict closed and idle peers from every room. Returns those removed.
+
+        Nothing calls this on a timer — when it runs is an application's
+        decision, because the right cadence depends on how long a stale
+        subscription actually costs anything.
+        """
+        removed: list[Peer] = []
+        for room in list(self._rooms):
+            for peer in list(self._rooms.get(room, ())):
+                if peer.closed or peer.is_idle():
+                    await self.leave(peer, room)
+                    if peer not in removed:
+                        removed.append(peer)
+        return removed
+
+    async def close(self) -> None:
+        """Close every peer and drop every room.
+
+        The rooms go first, before anything is awaited, so a broadcast racing
+        the shutdown finds an empty hub rather than a room whose peers are
+        half-closed.
+        """
+        peers = {p for members in self._rooms.values() for p in members}
+        self._rooms.clear()
+        # Concurrently, for the same reason a broadcast is: closing a thousand
+        # sockets one after another makes shutdown as slow as the slowest one.
+        await asyncio.gather(*(peer.close() for peer in peers))
+
+    def __repr__(self) -> str:
+        return f"<Hub rooms={len(self._rooms)} peers={self.count()}>"

sillo_wire/peer.py

@@ -0,0 +1,231 @@
+"""One connected client, with a bounded outbound queue.
+
+The queue is the point. Writing straight to a socket inside a fan-out means the
+slowest member of a room sets the pace for every other member: a client that
+has stopped reading fills its kernel buffer, the write blocks, and everyone
+behind it waits. Here a broadcast only ever *enqueues*, which cannot block, and
+a writer task per peer drains the queue at whatever rate that peer manages.
+
+What happens when a queue fills is a policy rather than a default -- see
+:class:`~sillo_wire.policy.Overflow`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+import typing
+import uuid
+
+from sillo_wire.envelope import Encoding, Envelope
+from sillo_wire.errors import PeerGone
+from sillo_wire.policy import Overflow
+
+__all__ = ["Peer"]
+
+#: Default queue depth. Deep enough to absorb a burst, shallow enough that a
+#: client which has genuinely stopped reading is noticed within a second or two
+#: rather than after megabytes have accumulated on its behalf.
+DEFAULT_CAPACITY = 64
+
+
+class Peer:
+    """A socket, its identity, and its outbound queue.
+
+    Args:
+        socket: The connection to write to. Anything with the
+            ``send_json`` / ``send_text`` / ``send_bytes`` trio works, which is
+            what makes a peer testable without a server.
+        encoding: How payloads are written.
+        identity: Who this connection belongs to, if anyone. Two peers may
+            share an identity — the same user with two tabs open — which is
+            what :meth:`~sillo_wire.hub.Hub.send_to` relies on.
+        capacity: Outbound queue depth.
+        overflow: What to do when the queue is full.
+        idle_timeout: Seconds of silence after which the peer is considered
+            stale. ``None`` disables the check.
+    """
+
+    __slots__ = (
+        "_closed",
+        "_queue",
+        "_writer",
+        "capacity",
+        "created_at",
+        "encoding",
+        "id",
+        "identity",
+        "idle_timeout",
+        "last_sent_at",
+        "overflow",
+        "socket",
+    )
+
+    def __init__(
+        self,
+        socket: typing.Any,
+        *,
+        encoding: Encoding = Encoding.JSON,
+        identity: typing.Any = None,
+        capacity: int = DEFAULT_CAPACITY,
+        overflow: Overflow = Overflow.DROP_OLDEST,
+        idle_timeout: float | None = None,
+    ) -> None:
+        if capacity < 1:
+            raise ValueError("capacity must be at least 1")
+
+        self.socket = socket
+        self.encoding = encoding
+        self.identity = identity
+        self.capacity = capacity
+        self.overflow = overflow
+        self.idle_timeout = idle_timeout
+
+        self.id = uuid.uuid4()
+        self.created_at = time.monotonic()
+        self.last_sent_at = self.created_at
+
+        self._queue: asyncio.Queue[Envelope] = asyncio.Queue(maxsize=capacity)
+        self._writer: asyncio.Task[None] | None = None
+        self._closed = False
+
+    # ── lifecycle ────────────────────────────────────────────────────────
+
+    @property
+    def closed(self) -> bool:
+        """Whether this peer has been closed, by either side."""
+        return self._closed
+
+    @property
+    def pending(self) -> int:
+        """Messages queued and not yet written."""
+        return self._queue.qsize()
+
+    def start(self) -> None:
+        """Begin draining the queue.
+
+        Idempotent, so a hub that joins the same peer to several rooms does not
+        start several writers for it.
+        """
+        if self._writer is None and not self._closed:
+            self._writer = asyncio.create_task(self._drain())
+
+    async def close(self) -> None:
+        """Stop the writer and close the socket.
+
+        Safe to call twice, and safe to call on a socket that is already gone —
+        a disconnect racing a cleanup is the normal case, not an error.
+        """
+        if self._closed:
+            return
+        self._closed = True
+
+        if self._writer is not None:
+            self._writer.cancel()
+            with contextlib.suppress(BaseException):
+                await self._writer
+            self._writer = None
+
+        # A socket that is already gone is the normal case here, not an error:
+        # close() is what runs when the client hung up.
+        with contextlib.suppress(Exception):
+            await self.socket.close()
+
+    # ── sending ──────────────────────────────────────────────────────────
+
+    def offer(self, envelope: Envelope) -> bool:
+        """Queue *envelope* without blocking. Returns whether it was accepted.
+
+        This is what a fan-out calls. It never awaits and never raises, so one
+        peer cannot affect the delivery of any other.
+        """
+        if self._closed:
+            return False
+
+        try:
+            self._queue.put_nowait(envelope)
+            return True
+        except asyncio.QueueFull:
+            return self._resolve_overflow(envelope)
+
+    def _resolve_overflow(self, envelope: Envelope) -> bool:
+        """Apply :attr:`overflow` to a message that did not fit."""
+        if self.overflow is Overflow.DROP_NEWEST:
+            return False
+
+        if self.overflow is Overflow.CLOSE:
+            # Closing is asynchronous, and this path must not await. Marking
+            # it closed stops further offers immediately; the writer task sees
+            # the flag and shuts the socket down.
+            self._closed = True
+            return False
+
+        # DROP_OLDEST: make room by discarding the head, then retry once. The
+        # retry cannot fail — nothing else consumes from this queue between the
+        # two calls, because neither of them awaits.
+        with contextlib.suppress(asyncio.QueueEmpty):
+            self._queue.get_nowait()
+        self._queue.put_nowait(envelope)
+        return True
+
+    async def send(self, payload: typing.Any) -> None:
+        """Write *payload* to the socket now, bypassing the queue.
+
+        For replies to that one peer, where the caller wants the failure. A
+        broadcast uses :meth:`offer` instead.
+
+        Raises:
+            PeerGone: If the peer is closed, or the socket raises.
+        """
+        if self._closed:
+            raise PeerGone(f"peer {self.id} is closed")
+        try:
+            await self._write(payload)
+        except Exception as exc:
+            raise PeerGone(f"peer {self.id} went away") from exc
+
+    async def _write(self, payload: typing.Any) -> None:
+        """Put one payload on the wire in this peer's encoding."""
+        if self.encoding is Encoding.JSON:
+            await self.socket.send_json(payload)
+        elif self.encoding is Encoding.TEXT:
+            await self.socket.send_text(payload)
+        else:
+            await self.socket.send_bytes(payload)
+        self.last_sent_at = time.monotonic()
+
+    async def _drain(self) -> None:
+        """Write queued envelopes until cancelled or the socket fails."""
+        while True:
+            envelope = await self._queue.get()
+            if self._closed:
+                break
+            try:
+                await self._write(envelope.payload)
+            except Exception:
+                # The socket is gone. Stop the writer rather than spinning on a
+                # dead connection; the hub notices through `closed` and evicts.
+                self._closed = True
+                break
+
+    # ── health ───────────────────────────────────────────────────────────
+
+    def is_idle(self, *, now: float | None = None) -> bool:
+        """Whether nothing has been written for longer than :attr:`idle_timeout`.
+
+        Distinct from a lifetime TTL on purpose: a connection that is being
+        used should not be evicted for having existed a long time, and one that
+        has gone quiet should be, however recently it connected.
+        """
+        if self.idle_timeout is None:
+            return False
+        moment = time.monotonic() if now is None else now
+        return (moment - self.last_sent_at) > self.idle_timeout
+
+    def __repr__(self) -> str:
+        state = "closed" if self._closed else f"pending={self.pending}"
+        return (
+            f"<Peer {str(self.id)[:8]} {self.encoding.value} "
+            f"identity={self.identity!r} {state}>"
+        )

sillo_wire/policy.py

@@ -0,0 +1,42 @@
+"""What to do when a peer cannot keep up.
+
+A socket that is not being read drains into the kernel's send buffer, and once
+that fills, a write blocks. In a fan-out that turns one slow client into a
+stall for everybody behind it, so every peer gets a bounded queue and a policy
+for what happens when the queue is full.
+"""
+
+from __future__ import annotations
+
+import enum
+
+__all__ = ["Overflow"]
+
+
+class Overflow(enum.Enum):
+    """What a peer does with a message it has no room for.
+
+    There is no good universal answer, only a choice about which property
+    matters more for the traffic in question.
+    """
+
+    DROP_OLDEST = "drop_oldest"
+    """Discard the queued message at the front and enqueue the new one.
+
+    Right for state that supersedes itself — a price tick, a cursor position, a
+    progress percentage. The client sees a gap but always sees *current*.
+    """
+
+    DROP_NEWEST = "drop_newest"
+    """Discard the message being sent and keep the queue as it is.
+
+    Right when order matters more than recency and the client will reconcile
+    from the backlog later.
+    """
+
+    CLOSE = "close"
+    """Disconnect the peer.
+
+    Right when a client that cannot keep up is a client that is broken, and
+    letting it reconnect is cheaper than reasoning about what it missed.
+    """

sillo_wire/testing.py

@@ -0,0 +1,86 @@
+"""Helpers for testing code that uses :mod:`sillo_wire`.
+
+Realtime code is awkward to test because the interesting behaviour is what a
+*socket* received, and a socket is the one thing a unit test does not have.
+:class:`FakeSocket` is that missing piece: it satisfies everything
+:class:`~sillo_wire.peer.Peer` calls and records what it was given.
+
+Nothing here is imported by the package itself, so it costs an application
+nothing at run time.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import typing
+
+from sillo_wire.peer import Peer
+
+__all__ = ["FakeSocket", "drain"]
+
+
+class FakeSocket:
+    """A stand-in for a WebSocket connection that records what it was sent.
+
+    Args:
+        delay: Seconds to sleep on each write. Non-zero simulates a client that
+            is slow to read, which is the case worth testing and the hardest to
+            reproduce with a real socket.
+        fail: Raise on every write, simulating a connection that has gone away.
+    """
+
+    __slots__ = ("closed", "delay", "fail", "sent")
+
+    def __init__(self, *, delay: float = 0.0, fail: bool = False) -> None:
+        self.sent: list[typing.Any] = []
+        self.delay = delay
+        self.fail = fail
+        self.closed = False
+
+    async def _record(self, payload: typing.Any) -> None:
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        if self.fail:
+            raise ConnectionResetError("fake socket is closed")
+        self.sent.append(payload)
+
+    async def send_json(self, payload: typing.Any) -> None:
+        """Record a JSON payload."""
+        await self._record(payload)
+
+    async def send_text(self, payload: str) -> None:
+        """Record a text payload."""
+        await self._record(payload)
+
+    async def send_bytes(self, payload: bytes) -> None:
+        """Record a bytes payload."""
+        await self._record(payload)
+
+    async def close(self, code: int = 1000) -> None:
+        """Mark the socket closed."""
+        self.closed = True
+
+    async def accept(self) -> None:
+        """Accept the connection."""
+
+
+async def drain(*peers: Peer, timeout: float = 1.0) -> None:
+    """Wait until every peer's queue is empty.
+
+    A broadcast only enqueues, so a test that asserts on ``socket.sent``
+    straight afterwards is racing the writer task. This is the wait that makes
+    such an assertion deterministic.
+
+    Raises:
+        TimeoutError: If the queues have not emptied within *timeout*, which
+            means a writer is stuck rather than slow.
+    """
+
+    async def _wait() -> None:
+        while any(peer.pending for peer in peers):
+            await asyncio.sleep(0)
+        # One more yield so the write that emptied the queue completes before
+        # the caller inspects what the socket received.
+        await asyncio.sleep(0)
+
+    await asyncio.wait_for(_wait(), timeout=timeout)