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

sillo_wire-0.1.0.dev1.dist-info/METADATA

@@ -0,0 +1,244 @@
+Metadata-Version: 2.5
+Name: sillo-wire
+Version: 0.1.0.dev1
+Summary: Rooms, presence and fan-out for Sillo WebSockets — bounded queues, replayable backlog, no global state.
+Project-URL: Homepage, https://sillo.build
+Project-URL: Documentation, https://docs.sillo.build/packages/wire/
+Project-URL: Source, https://github.com/sillohq/wire
+Author-email: Chidebele Dunamis <techwithdunamix@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: asgi,broadcast,presence,pubsub,realtime,sillo,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.10
+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 :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: sillo-framework>=0.3
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sillo-wire
+
+Rooms, presence and fan-out for [Sillo](https://sillo.build) WebSockets.
+
+```bash
+pip install sillo-wire
+```
+
+Installs as `sillo-wire`, imports as `sillo.wire`.
+
+```python
+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)
+```
+
+## Why this exists
+
+Three things differ from the obvious implementation, and they are the whole
+point of the package.
+
+**A broadcast never blocks.** Writing straight to each socket in turn means the
+slowest member of a room sets the pace for everyone else — a client that has
+stopped reading fills its kernel buffer, the write blocks, and the rest of the
+room waits behind it. Here every peer has a bounded queue and a writer task, so
+a broadcast only ever enqueues:
+
+```python
+report = await hub.broadcast("lobby", {"msg": "hello"})
+report.delivered   # 41
+report.dropped     #  2   queues were full
+report.failed      #  1   socket was already gone
+```
+
+You get a `DeliveryReport` rather than nothing, because a fan-out you cannot
+measure is a fan-out you cannot operate.
+
+**Nothing is global.** A `Hub` is an ordinary object. Two of them are two
+independent worlds, so tests get a fresh one per case instead of remembering to
+flush shared state, and a multi-tenant application keeps traffic apart without
+a naming convention.
+
+**History is replayable.** Every envelope carries a monotonic sequence, so a
+client that reconnects asks for what it missed rather than for everything or
+for nothing:
+
+```python
+await hub.replay(peer, "lobby", since=last_seq_the_client_saw)
+```
+
+## Slow consumers
+
+When a peer's queue fills, what happens is a choice, not a default:
+
+```python
+from sillo.wire import Overflow, Peer
+
+Peer(socket, overflow=Overflow.DROP_OLDEST)   # keep current — prices, cursors
+Peer(socket, overflow=Overflow.DROP_NEWEST)   # keep order — reconcile later
+Peer(socket, overflow=Overflow.CLOSE)         # disconnect and let it reconnect
+```
+
+## Presence
+
+```python
+@hub.on_join
+async def joined(room, peer):
+    await hub.broadcast(room, {"event": "joined", "who": peer.identity})
+
+hub.identities("lobby")   # ["ada", "bob"] — people, not sockets
+hub.count("lobby")        # 5 — subscriptions
+```
+
+Two peers can share an identity — the same person with a phone and two tabs —
+and `send_to` reaches all of them:
+
+```python
+await hub.send_to("ada", {"notice": "your export is ready"})
+```
+
+## Consumers
+
+`RoomConsumer` is the class-based form. It accepts the socket, builds the peer,
+joins the rooms, pumps messages, and guarantees the peer is removed from every
+room when the connection ends — including when a hook raises.
+
+```python
+from sillo.wire import Hub, RoomConsumer
+
+hub = Hub()
+
+class Chat(RoomConsumer):
+    hub = hub
+
+    async def identify(self, ctx):
+        return ctx.query_params.get("user")
+
+    async def rooms(self, ctx):
+        return [ctx.path_params["room"]]
+
+    async def on_message(self, data):
+        await self.broadcast({"from": self.peer.identity, "text": data})
+
+app.add_ws_route(path="/ws/{room}", handler=Chat.as_handler())
+```
+
+## Backlog
+
+Retention is per room and capped by payload bytes, evicting oldest first:
+
+```python
+from sillo.wire import Hub, MemoryBacklog, NullBacklog
+
+Hub(backlog=MemoryBacklog(capacity_bytes=4 * 1024 * 1024))
+Hub(backlog=NullBacklog())    # keep nothing — typing indicators, telemetry
+```
+
+`Backlog` is a `Protocol`, so a Redis or Postgres store satisfies it without
+importing anything from here.
+
+## Testing
+
+`sillo.wire.testing` ships the piece unit tests are missing — a socket:
+
+```python
+from sillo.wire import Hub, Peer
+from sillo_wire.testing import FakeSocket, drain
+
+async def test_a_broadcast_reaches_the_room():
+    hub, socket = Hub(), FakeSocket()
+    peer = Peer(socket)
+    await hub.join(peer, "lobby")
+
+    await hub.broadcast("lobby", {"hello": True})
+    await drain(peer)          # broadcasts enqueue; this waits for the write
+
+    assert socket.sent == [{"hello": True}]
+```
+
+`FakeSocket(delay=…)` simulates a client that is slow to read, and
+`FakeSocket(fail=True)` one that has gone away — the two cases that are hardest
+to reproduce against a real server and the two most worth testing.
+
+## Reference
+
+| | |
+|---|---|
+| `Hub` | `join` `leave` `leave_all` `disconnect` `broadcast` `send_to` `replay` `history` `clear_history` `on_join` `on_leave` `rooms` `members` `identities` `count` `prune` `close` |
+| `Peer` | `offer` `send` `start` `close` `is_idle` `closed` `pending` `identity` |
+| `Envelope` | `payload` `room` `seq` `sent_at` `size()` |
+| `DeliveryReport` | `delivered` `dropped` `failed` `attempted` |
+| `Backlog` | `MemoryBacklog` `NullBacklog`, or your own |
+| `Overflow` | `DROP_OLDEST` `DROP_NEWEST` `CLOSE` |
+
+## The two import paths
+
+`sillo.wire` and `sillo_wire` name the same objects. The code lives in the
+top-level `sillo_wire` package; `sillo.wire` is an alias, so it reads as part
+of the framework:
+
+```python
+from sillo.wire import Hub     # both of these
+from sillo_wire import Hub     # bind the same class
+```
+
+The alias is a meta-path finder registered by a `.pth` at interpreter startup —
+the only hook that runs before an `import sillo.wire` could fail. Type checkers
+never run import hooks, so they are served separately by the partial stubs in
+`sillo-stubs/` (PEP 561), which are additive: mypy resolves `sillo.wire` and
+still uses the framework's own inline types for the rest of `sillo`.
+
+Nothing is written into the framework's package directory. Shipping
+`sillo/wire/` in there would be simpler, and it is what this did first — but
+two distributions sharing one directory goes wrong in both directions.
+Installing the framework from a checkout moves where `sillo` resolves and
+orphans the copy in site-packages; removing or replacing the framework leaves
+that directory standing with no `__init__.py`, which is an override rather than
+an addition. Uninstalling either package here leaves the other exactly as it
+was.
+
+## Working on it
+
+The alias works under an editable install too — the `.pth` is shipped by the
+editable build target as well as the wheel.
+
+```bash
+pip install -e ".[dev]"
+pytest --cov            # 100% required, bootstrap included
+ruff check sillo_wire tests _sillo_wire_bootstrap.py
+mypy sillo_wire
+```
+
+## Requirements
+
+Python 3.10+, `sillo-framework` 0.3 or newer. No other dependencies.
+
+## Licence
+
+BSD-3-Clause.

sillo_wire-0.1.0.dev1.dist-info/RECORD

@@ -0,0 +1,18 @@
+sillo-stubs/py.typed,sha256=la67KBlbjXN-_-DfGNcdOcjYumVpKG_Tkw-8n5dnGB4,8
+sillo-stubs/wire.pyi,sha256=JPl9KrNkBmSbC0uhwOSHokHhImU-Vy88a7I66IQpJKM,1599
+sillo_wire/__init__.py,sha256=IUQu2nkvHUdZ1aeqTNOXjCRfjsT4fYjw1lx62-2oIPo,1778
+sillo_wire/backlog.py,sha256=xp4eh3lrDugrDy5-kQm1OJi9ksZpL_fMrhI8ittNIXU,4989
+sillo_wire/consumer.py,sha256=z5mfCmXCWDyGjL7Y0loGPSJmZAHNQWYLj1fOqqakd1M,6782
+sillo_wire/envelope.py,sha256=NQJz4Vurmj7pLhXPuGHWNkfPo3rmRr_PrFwgwIRGEwA,3022
+sillo_wire/errors.py,sha256=AzFwuRu4TyE7PYlPZay66NJKPHYwlMu7BW3CCiQN7fA,969
+sillo_wire/hub.py,sha256=71l4-AXNWV7zSH_420YSjrSgkZ57Df1U6Xy8T0Vo5zM,12181
+sillo_wire/peer.py,sha256=i1VYbxer30jb1m0HS9u5XbSnhhJHDCJGqh45wFCxlN8,8594
+sillo_wire/policy.py,sha256=bZWrtA40kwZ-X9ZI69osROZmpFwiGlAlPODsKc7y_8k,1302
+sillo_wire/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sillo_wire/testing.py,sha256=gLJCviZadqJ1CyLnFukRajvwZNu2DaCQ-XTyX7a5JM4,2849
+_sillo_wire_bootstrap.py,sha256=An8k-vTkg-dTEs4Wm_pzf-Kh1XUBPiRp24mC6IFcczA,3720
+sillo_wire.pth,sha256=t_fzMs4Twwhhm0yv7-lbUsXEWyzBjHh3MOq8RYVDpJQ,29
+sillo_wire-0.1.0.dev1.dist-info/METADATA,sha256=qIVNR1kTDwmESRWwu6w3eThoMSYO-kKTkkoPctVZAXQ,8094
+sillo_wire-0.1.0.dev1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+sillo_wire-0.1.0.dev1.dist-info/licenses/LICENSE,sha256=SYnJBmVg6ElC6Nx4oK_kH5R5A6wVeKLU0kyf-_UzZs8,1528
+sillo_wire-0.1.0.dev1.dist-info/RECORD,,

sillo_wire-0.1.0.dev1.dist-info/WHEEL

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

sillo_wire-0.1.0.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,27 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-present, sillo-Labs OSS.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sillo_wire.pth

@@ -0,0 +1 @@
+import _sillo_wire_bootstrap