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

_sillo_wire_bootstrap.py

@@ -0,0 +1,104 @@
+"""Make ``sillo.wire`` resolve to this package, without touching the framework.
+
+The code lives in the top-level ``sillo_wire`` package. This module registers a
+meta-path finder that maps the name ``sillo.wire`` onto it, so both import
+paths reach the same objects:
+
+    from sillo.wire import Hub      # reads as part of the framework
+    from sillo_wire import Hub      # where the code actually is
+
+It is loaded by ``sillo_wire.pth`` at interpreter startup, which is the only
+hook that runs *before* an ``import sillo.wire`` could fail. Nothing is
+imported here — neither ``sillo`` nor ``sillo_wire`` — so the cost is one
+object appended to ``sys.meta_path``.
+
+Why not simply ship ``sillo/wire/`` into the framework's own package directory:
+two distributions writing into one directory goes wrong in both directions.
+Installing the framework from a checkout moves where ``sillo`` resolves and
+orphans whatever the other package left in ``site-packages``; and removing or
+replacing the framework leaves that directory standing with no ``__init__.py``
+in it, which is an override rather than an addition. Nothing here writes into
+``sillo/`` at all.
+
+Static analysis does not run import hooks, so type checkers are served
+separately, by the partial stubs in ``sillo-stubs/`` (PEP 561).
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib.abc import Loader, MetaPathFinder
+from importlib.machinery import ModuleSpec
+from importlib.util import find_spec
+
+ALIAS = "sillo.wire"
+REAL = "sillo_wire"
+
+
+def _resolve(fullname: str) -> str | None:
+    """The real module *fullname* stands for, or ``None`` if it is not ours."""
+    if fullname == ALIAS:
+        return REAL
+    if fullname.startswith(ALIAS + "."):
+        return REAL + fullname[len(ALIAS) :]
+    return None
+
+
+class _AliasLoader(Loader):
+    """Hands back the already-imported target, so both names are one object.
+
+    Loading the source a second time under the other name would give two
+    ``Hub`` classes and two sets of rooms — a broadcast would reach half of
+    them, and ``isinstance`` would disagree with itself.
+    """
+
+    def __init__(self, target: str) -> None:
+        self.target = target
+
+    def create_module(self, spec: ModuleSpec):
+        import importlib
+
+        return importlib.import_module(self.target)
+
+    def exec_module(self, module) -> None:
+        """Already executed under its own name; nothing to run again."""
+
+
+class _AliasFinder(MetaPathFinder):
+    """Answers for ``sillo.wire`` and anything beneath it."""
+
+    def find_spec(self, fullname: str, path=None, target=None):
+        real = _resolve(fullname)
+        if real is None:
+            return None
+        try:
+            if find_spec(real) is None:
+                return None
+        except (ImportError, ValueError):
+            # The package is half-installed, or its parent is missing. Decline
+            # rather than raise: another finder may do better, and the import
+            # error a caller gets should be the ordinary one.
+            return None
+
+        import importlib
+
+        module = importlib.import_module(real)
+        spec = ModuleSpec(fullname, _AliasLoader(real))
+        spec.submodule_search_locations = getattr(module, "__path__", None)
+        return spec
+
+
+def install() -> bool:
+    """Register the finder. Returns whether it was newly added.
+
+    Idempotent, because a ``.pth`` is not the only thing that may import this
+    module — a test does too, and a second finder would be dead weight on every
+    import in the process.
+    """
+    if any(isinstance(finder, _AliasFinder) for finder in sys.meta_path):
+        return False
+    sys.meta_path.insert(0, _AliasFinder())
+    return True
+
+
+install()

sillo-stubs/py.typed

@@ -0,0 +1 @@
+partial

sillo-stubs/wire.pyi

@@ -0,0 +1,48 @@
+"""Type stubs for ``sillo.wire``.
+
+The runtime alias is installed by ``_sillo_wire_bootstrap`` via a ``.pth``, and
+a type checker never runs import hooks — so without this file
+``from sillo.wire import Hub`` type-checks as a missing module even though it
+imports fine.
+
+``py.typed`` next to this file contains the word ``partial`` (PEP 561), which
+is what keeps these stubs additive: a checker uses them for ``sillo.wire`` and
+falls back to the framework's own inline types for the rest of ``sillo``.
+Without it, this directory would claim to describe all of ``sillo`` and hide
+the types the framework ships.
+
+Nothing is declared here. Everything is re-exported from ``sillo_wire``, whose
+inline annotations are the single source of truth.
+"""
+
+from sillo_wire import Backlog as Backlog
+from sillo_wire import DeliveryReport as DeliveryReport
+from sillo_wire import Encoding as Encoding
+from sillo_wire import Envelope as Envelope
+from sillo_wire import Hub as Hub
+from sillo_wire import MemoryBacklog as MemoryBacklog
+from sillo_wire import NullBacklog as NullBacklog
+from sillo_wire import Overflow as Overflow
+from sillo_wire import Peer as Peer
+from sillo_wire import PeerGone as PeerGone
+from sillo_wire import RoomConsumer as RoomConsumer
+from sillo_wire import RoomNotFound as RoomNotFound
+from sillo_wire import WireError as WireError
+
+__version__: str
+
+__all__ = [
+    "Backlog",
+    "DeliveryReport",
+    "Encoding",
+    "Envelope",
+    "Hub",
+    "MemoryBacklog",
+    "NullBacklog",
+    "Overflow",
+    "Peer",
+    "PeerGone",
+    "RoomConsumer",
+    "RoomNotFound",
+    "WireError",
+]

sillo_wire/__init__.py

@@ -0,0 +1,58 @@
+"""Rooms, presence and fan-out for Sillo WebSockets.
+
+Install as ``sillo-wire``; import as ``sillo_wire``::
+
+    from sillo import SilloApp
+    from sillo_wire import Hub, Peer
+
+    app = SilloApp()
+    hub = Hub()
+
+    @app.ws_route("/ws/room/{name}")
+    async def room(socket, name: str):
+        await socket.accept()
+        peer = Peer(socket, identity=socket.query_params.get("user"))
+        await hub.join(peer, name)
+        try:
+            async for message in socket.iter_json():
+                await hub.broadcast(name, message)
+        finally:
+            await hub.disconnect(peer)
+
+Three things differ from a naive implementation, and they are the reason this
+package exists:
+
+* **A broadcast never blocks.** Peers have bounded queues and a writer each, so
+  one client that has stopped reading cannot stall the room behind it.
+* **Nothing is global.** A :class:`Hub` is an object. Two of them are two
+  independent worlds, which is what makes tests and multi-tenancy simple.
+* **History is replayable.** Envelopes carry a monotonic sequence, so a client
+  that reconnects asks for what it missed rather than for everything.
+"""
+
+from sillo_wire.backlog import Backlog, MemoryBacklog, NullBacklog
+from sillo_wire.consumer import RoomConsumer
+from sillo_wire.envelope import DeliveryReport, Encoding, Envelope
+from sillo_wire.errors import PeerGone, RoomNotFound, WireError
+from sillo_wire.hub import Hub
+from sillo_wire.peer import Peer
+from sillo_wire.policy import Overflow
+
+__version__ = "0.1.0.dev1"
+
+__all__ = [
+    "Backlog",
+    "DeliveryReport",
+    "Encoding",
+    "Envelope",
+    "Hub",
+    "MemoryBacklog",
+    "NullBacklog",
+    "Overflow",
+    "Peer",
+    "PeerGone",
+    "RoomConsumer",
+    "RoomNotFound",
+    "WireError",
+    "__version__",
+]

sillo_wire/backlog.py

@@ -0,0 +1,140 @@
+"""Recent traffic per room, and where a reconnecting client left off.
+
+A backlog is what turns a dropped connection into a gap a client can close. It
+keeps the last N bytes of a room's envelopes and answers "everything after
+sequence 42", which is the question a client actually has after reconnecting.
+
+The memory implementation caps by *payload* bytes and evicts oldest-first.
+Sizing a list of messages with :func:`sys.getsizeof` measures the list's
+pointer array rather than the messages, so a "1 MB" cap set that way holds
+whatever fits in 1 MB of pointers — a hundred times its stated limit — and
+then, on tripping, discards the entire history rather than the oldest part of
+it. Both of those are the bug this exists to not have.
+"""
+
+from __future__ import annotations
+
+import typing
+from collections import deque
+
+from sillo_wire.envelope import Envelope
+
+__all__ = ["Backlog", "MemoryBacklog", "NullBacklog"]
+
+#: One mebibyte per room, which is a few thousand chat messages and a few
+#: hundred sizeable JSON documents.
+DEFAULT_CAPACITY_BYTES = 1_048_576
+
+
+class Backlog(typing.Protocol):
+    """What a hub needs from a message store.
+
+    A protocol rather than a base class so a Redis or Postgres implementation
+    does not have to import anything from here to satisfy it.
+    """
+
+    async def append(self, envelope: Envelope) -> None:
+        """Record *envelope* against its room."""
+        ...
+
+    async def since(self, room: str, seq: int) -> list[Envelope]:
+        """Every retained envelope for *room* newer than *seq*, oldest first."""
+        ...
+
+    async def latest(self, room: str, limit: int = 50) -> list[Envelope]:
+        """The most recent *limit* envelopes for *room*, oldest first."""
+        ...
+
+    async def clear(self, room: str | None = None) -> None:
+        """Forget one room's history, or all of it."""
+        ...
+
+
+class MemoryBacklog:
+    """Per-room history in memory, capped by payload bytes.
+
+    Args:
+        capacity_bytes: How much payload to retain per room. Eviction is
+            oldest-first, so the cap trims the tail of the history rather than
+            emptying it.
+    """
+
+    __slots__ = ("_bytes", "_rooms", "capacity_bytes")
+
+    def __init__(self, capacity_bytes: int = DEFAULT_CAPACITY_BYTES) -> None:
+        if capacity_bytes < 1:
+            raise ValueError("capacity_bytes must be at least 1")
+        self.capacity_bytes = capacity_bytes
+        self._rooms: dict[str, deque[Envelope]] = {}
+        self._bytes: dict[str, int] = {}
+
+    async def append(self, envelope: Envelope) -> None:
+        """Record *envelope*, evicting oldest until the room fits its cap."""
+        room = envelope.room
+        entries = self._rooms.setdefault(room, deque())
+        entries.append(envelope)
+        self._bytes[room] = self._bytes.get(room, 0) + envelope.size()
+
+        # A single envelope larger than the whole cap would loop forever if the
+        # room could be emptied; stopping at one entry keeps the most recent
+        # message retrievable, which is more useful than an empty room.
+        while len(entries) > 1 and self._bytes[room] > self.capacity_bytes:
+            self._bytes[room] -= entries.popleft().size()
+
+    async def since(self, room: str, seq: int) -> list[Envelope]:
+        """Everything retained for *room* after *seq*."""
+        return [e for e in self._rooms.get(room, ()) if e.seq > seq]
+
+    async def latest(self, room: str, limit: int = 50) -> list[Envelope]:
+        """The last *limit* envelopes for *room*."""
+        if limit <= 0:
+            return []
+        entries = self._rooms.get(room)
+        if not entries:
+            return []
+        return list(entries)[-limit:]
+
+    async def clear(self, room: str | None = None) -> None:
+        """Forget *room*, or every room."""
+        if room is None:
+            self._rooms.clear()
+            self._bytes.clear()
+            return
+        self._rooms.pop(room, None)
+        self._bytes.pop(room, None)
+
+    def usage(self, room: str) -> int:
+        """Bytes currently retained for *room*.
+
+        Exposed because a cap you cannot observe is a cap you cannot tune.
+        """
+        return self._bytes.get(room, 0)
+
+    def rooms(self) -> list[str]:
+        """Every room this backlog holds something for."""
+        return list(self._rooms)
+
+
+class NullBacklog:
+    """Keeps nothing.
+
+    The right choice for traffic that is worthless a second later — cursors,
+    typing indicators, telemetry — where retaining it costs memory and buys
+    nobody anything.
+    """
+
+    __slots__ = ()
+
+    async def append(self, envelope: Envelope) -> None:
+        """Discard *envelope*."""
+
+    async def since(self, room: str, seq: int) -> list[Envelope]:
+        """Always empty."""
+        return []
+
+    async def latest(self, room: str, limit: int = 50) -> list[Envelope]:
+        """Always empty."""
+        return []
+
+    async def clear(self, room: str | None = None) -> None:
+        """Nothing to clear."""

sillo_wire/consumer.py

@@ -0,0 +1,177 @@
+"""A class-based endpoint with the room plumbing already wired.
+
+:class:`RoomConsumer` is the ergonomic layer over :class:`~sillo_wire.hub.Hub`
+and :class:`~sillo_wire.peer.Peer`: it accepts the socket, builds the peer,
+joins the rooms, pumps messages into :meth:`~RoomConsumer.on_message`, and
+guarantees the peer is removed from every room when the connection ends —
+including when the handler raises.
+
+Subclass it and override the hooks you need::
+
+    class Chat(RoomConsumer):
+        hub = my_hub
+
+        async def rooms(self, ctx):
+            return [ctx.path_params["room"]]
+
+        async def on_message(self, data):
+            await self.broadcast(data)
+"""
+
+from __future__ import annotations
+
+import typing
+
+from sillo_wire.envelope import DeliveryReport, Encoding
+from sillo_wire.hub import Hub
+from sillo_wire.peer import Peer
+from sillo_wire.policy import Overflow
+
+__all__ = ["RoomConsumer"]
+
+
+class RoomConsumer:
+    """One connection's lifecycle, from accept to cleanup.
+
+    A fresh instance is created per connection, so ``self`` is a safe place to
+    keep per-connection state — unlike the hub, which is shared.
+    """
+
+    #: The hub this consumer joins rooms on. Override per subclass, or pass one
+    #: to :meth:`as_handler`.
+    hub: typing.ClassVar[Hub | None] = None
+
+    #: How payloads are written, and which ``iter_*`` the read loop uses.
+    encoding: typing.ClassVar[Encoding] = Encoding.JSON
+
+    #: Outbound queue depth per connection.
+    capacity: typing.ClassVar[int] = 64
+
+    #: What happens when a connection cannot keep up.
+    overflow: typing.ClassVar[Overflow] = Overflow.DROP_OLDEST
+
+    def __init__(self, hub: Hub | None = None) -> None:
+        resolved = hub if hub is not None else self.hub
+        if resolved is None:
+            raise ValueError(
+                f"{type(self).__name__} has no hub: set `hub` on the class or "
+                f"pass one to as_handler()"
+            )
+        self._hub: Hub = resolved
+        self.peer: Peer | None = None
+        self.ctx: typing.Any = None
+        self.joined: list[str] = []
+
+    # ── registration ─────────────────────────────────────────────────────
+
+    @classmethod
+    def as_handler(cls, hub: Hub | None = None) -> typing.Callable[..., typing.Any]:
+        """Build the coroutine to hand to ``@app.ws_route``.
+
+        Path parameters arrive as keyword arguments, exactly as on an HTTP
+        route, and are forwarded to :meth:`rooms` through the context rather
+        than to the hooks — the hooks have a fixed shape so subclasses do not
+        each have to declare them.
+        """
+
+        async def handler(ctx: typing.Any, **params: typing.Any) -> None:
+            await cls(hub)(ctx)
+
+        return handler
+
+    # ── the loop ─────────────────────────────────────────────────────────
+
+    async def __call__(self, ctx: typing.Any) -> None:
+        """Run one connection to completion."""
+        self.ctx = ctx
+        await ctx.accept()
+
+        self.peer = Peer(
+            ctx,
+            encoding=self.encoding,
+            identity=await self.identify(ctx),
+            capacity=self.capacity,
+            overflow=self.overflow,
+        )
+
+        try:
+            for room in await self.rooms(ctx):
+                await self._hub.join(self.peer, room)
+                self.joined.append(room)
+
+            await self.on_connect()
+            await self._pump()
+        finally:
+            # Runs on a clean close, a client disconnect, and an exception in a
+            # hook alike. Leaving a peer subscribed after its socket is gone is
+            # the leak this exists to prevent.
+            await self.on_disconnect()
+            await self._hub.disconnect(self.peer)
+
+    async def _pump(self) -> None:
+        """Read from the socket until it closes, dispatching each message."""
+        iterator = {
+            Encoding.JSON: "iter_json",
+            Encoding.TEXT: "iter_text",
+            Encoding.BYTES: "iter_bytes",
+        }[self.encoding]
+
+        async for message in getattr(self.ctx, iterator)():
+            await self.on_message(message)
+
+    # ── helpers ──────────────────────────────────────────────────────────
+
+    async def broadcast(
+        self, payload: typing.Any, room: str | None = None
+    ) -> DeliveryReport:
+        """Send *payload* to *room*, defaulting to the first room joined."""
+        target = room if room is not None else (self.joined[0] if self.joined else None)
+        if target is None:
+            return DeliveryReport()
+        return await self._hub.broadcast(target, payload)
+
+    async def reply(self, payload: typing.Any) -> None:
+        """Send *payload* to this connection alone."""
+        if self.peer is not None:
+            await self.peer.send(payload)
+
+    async def join(self, room: str) -> bool:
+        """Subscribe this connection to another room."""
+        if self.peer is None:  # pragma: no cover - unreachable inside __call__
+            return False
+        added = await self._hub.join(self.peer, room)
+        if added:
+            self.joined.append(room)
+        return added
+
+    async def leave(self, room: str) -> bool:
+        """Unsubscribe this connection from *room*."""
+        if self.peer is None:  # pragma: no cover - unreachable inside __call__
+            return False
+        removed = await self._hub.leave(self.peer, room)
+        if removed and room in self.joined:
+            self.joined.remove(room)
+        return removed
+
+    # ── hooks ────────────────────────────────────────────────────────────
+
+    async def identify(self, ctx: typing.Any) -> typing.Any:
+        """Who this connection belongs to. ``None`` means anonymous.
+
+        Called once, before any room is joined, so the identity is already set
+        when presence listeners fire.
+        """
+        return None
+
+    async def rooms(self, ctx: typing.Any) -> list[str]:
+        """Which rooms to join on connect. Defaults to none."""
+        return []
+
+    async def on_connect(self) -> None:
+        """Called once the peer is in its rooms."""
+
+    async def on_message(self, data: typing.Any) -> None:
+        """Called for each message received. Override this."""
+
+    async def on_disconnect(self) -> None:
+        """Called once as the connection ends, before the peer is removed."""

sillo_wire/envelope.py

@@ -0,0 +1,92 @@
+"""The unit of traffic, and the result of sending one.
+
+An :class:`Envelope` is what a room stores and replays. It carries a monotonic
+:attr:`~Envelope.seq` so a client that reconnects can say "everything after
+42" rather than "everything" or "nothing" -- see :meth:`Backlog.since`.
+"""
+
+from __future__ import annotations
+
+import enum
+import itertools
+import typing
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+__all__ = ["DeliveryReport", "Encoding", "Envelope"]
+
+#: Process-wide sequence source. Monotonic rather than time-based because two
+#: envelopes created in the same microsecond must still order, and a clock that
+#: steps backwards must not make a replay cursor skip.
+_counter = itertools.count(1)
+
+
+class Encoding(enum.Enum):
+    """How a payload is written to the socket."""
+
+    JSON = "json"
+    TEXT = "text"
+    BYTES = "bytes"
+
+
+@dataclass(frozen=True, slots=True)
+class Envelope:
+    """One message, addressed to a room.
+
+    Frozen because an envelope handed to a fan-out is shared by every peer in
+    the room; a mutable one would let a slow peer observe an edit made after it
+    was queued.
+    """
+
+    payload: typing.Any
+    room: str = ""
+    seq: int = field(default_factory=lambda: next(_counter))
+    #: Factories rather than plain defaults: a plain default is evaluated once,
+    #: at class definition, which would stamp every envelope in a backlog with
+    #: the same import-time timestamp.
+    sent_at: datetime = field(
+        default_factory=lambda: datetime.now(tz=timezone.utc)
+    )
+
+    def size(self) -> int:
+        """Roughly what this costs to hold, in bytes.
+
+        Used by the backlog to enforce its cap. Exact for the encodings that
+        have a length and estimated otherwise, which is the right trade for a
+        limit whose purpose is to stop unbounded growth rather than to account
+        precisely.
+        """
+        payload = self.payload
+        if isinstance(payload, (bytes, bytearray, memoryview)):
+            return len(payload)
+        if isinstance(payload, str):
+            return len(payload.encode("utf-8", "replace"))
+        return len(repr(payload).encode("utf-8", "replace"))
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryReport:
+    """What a fan-out actually did.
+
+    A broadcast that returns nothing is a broadcast you cannot operate: there
+    is no way to tell "nobody was listening" from "everybody was, and half of
+    them failed".
+    """
+
+    delivered: int = 0
+    """Peers the message was written to."""
+
+    dropped: int = 0
+    """Peers whose queue was full, resolved by their overflow policy."""
+
+    failed: int = 0
+    """Peers whose socket raised while being written to."""
+
+    @property
+    def attempted(self) -> int:
+        """Every peer the room contained when the fan-out began."""
+        return self.delivered + self.dropped + self.failed
+
+    def __bool__(self) -> bool:
+        """True when at least one peer received the message."""
+        return self.delivered > 0

sillo_wire/errors.py

@@ -0,0 +1,30 @@
+"""Exceptions raised by :mod:`sillo_wire`.
+
+All of them derive from :class:`WireError`, so an application that wants to
+treat "the realtime layer failed" as one case can catch that and nothing else.
+"""
+
+from __future__ import annotations
+
+__all__ = ["PeerGone", "RoomNotFound", "WireError"]
+
+
+class WireError(Exception):
+    """Base class for every error this package raises."""
+
+
+class PeerGone(WireError):
+    """A peer's socket is closed, or closed while being written to.
+
+    Raised only by the explicit single-peer sends. A broadcast never raises
+    this — one dead subscriber is an ordinary event in a fan-out, and is
+    reported through :class:`~sillo_wire.envelope.DeliveryReport` instead.
+    """
+
+
+class RoomNotFound(WireError):
+    """A room was addressed by name and no such room exists.
+
+    Like :class:`PeerGone`, this is raised by direct operations rather than by
+    broadcasts, where an empty room is a normal outcome and not a failure.
+    """