sillo-wire 0.1.0.dev1__tar.gz

sillo_wire-0.1.0.dev1/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install sillo-framework
+          pip install pytest pytest-asyncio pytest-cov ruff mypy
+
+      - name: Lint
+        run: ruff check sillo_wire tests _sillo_wire_bootstrap.py
+
+      - name: Types
+        run: mypy sillo_wire
+
+      - name: Install the package
+        run: pip install -e .
+
+      # The `.pth` only fires for a real install, so the alias is checked
+      # against a built wheel rather than the editable checkout.
+      - name: Check the sillo.wire alias against a real install
+        run: |
+          pip install build && python -m build --wheel -o /tmp/w .
+          python -m venv /tmp/v && /tmp/v/bin/pip install -q sillo-framework /tmp/w/*.whl mypy
+          /tmp/v/bin/python -c "
+          import sillo, sillo.wire, sillo_wire, os
+          assert sillo.wire is sillo_wire
+          assert 'wire' not in os.listdir(os.path.dirname(sillo.__file__)), 'wrote into sillo/'
+          print('alias ok, sillo/ untouched')
+          "
+          printf 'from sillo.wire import Hub\nh: Hub = Hub()\n' > /tmp/tc.py
+          /tmp/v/bin/python -m mypy /tmp/tc.py
+
+      - name: Test
+        run: pytest --cov --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      # The wheel must not write anything into the framework's own package
+      # directory — that is the collision this layout exists to avoid.
+      - name: Check the wheel stays out of sillo/
+        run: |
+          python - <<'PY'
+          import zipfile, glob
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          modules = [n for n in names if not n.startswith("sillo_wire-")]
+          assert not any(n.startswith("sillo/") for n in names), "must not touch sillo/"
+          assert not any(n.startswith("sillo/") for n in names), "must not touch sillo/"
+          print("\n".join(modules))
+          PY

sillo_wire-0.1.0.dev1/.github/workflows/release.yml

@@ -0,0 +1,103 @@
+name: Release on Tag
+
+on:
+  push:
+    tags:
+      - 'sillo-wire-v*'  # sillo-wire releases: sillo-wire-v0.1.0
+
+jobs:
+  release:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read        # actions/checkout needs repo read access
+      id-token: write       # for OIDC (trusted publishing)
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          TAG="${{ github.ref_name }}"
+          VERSION="${TAG#sillo-wire-v}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "📦 Releasing sillo-wire v$VERSION"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      # PyPI takes the version from the package, not the tag. Without this a
+      # tag of sillo-wire-v0.1.1 against a pyproject still saying 0.1.0
+      # publishes 0.1.0 and reports success, and the version it claims to have
+      # released is one that does not exist.
+      #
+      # `sillo_wire.__version__` is checked too because it is what a user reads
+      # at runtime.
+      - name: The tag, the package and __version__ must agree
+        run: |
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          PKG_VERSION=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          MOD_VERSION=$(python -c "import re,pathlib; print(re.search(r'__version__.*?\"(.*?)\"', pathlib.Path('sillo_wire/__init__.py').read_text()).group(1))")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag says $TAG_VERSION, pyproject.toml says $PKG_VERSION."
+            exit 1
+          fi
+          if [ "$TAG_VERSION" != "$MOD_VERSION" ]; then
+            echo "::error::Tag says $TAG_VERSION, sillo_wire/__init__.py says $MOD_VERSION."
+            exit 1
+          fi
+          echo "all three say $PKG_VERSION"
+
+      - name: Clean Old Builds
+        run: |
+          rm -rf dist build *.egg-info
+
+      - name: Setup Virtual Environment
+        run: uv venv
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Run tests
+        run: uv run pytest -q --tb=short
+
+      - name: Build the package
+        run: uv build
+
+      # The whole point of this package's layout: the wheel adds a top-level
+      # `sillo_wire` plus the `.pth`/bootstrap at the site-packages root, and
+      # it must never write into the framework's own `sillo/` directory.
+      - name: The wheel must stay out of sillo/
+        run: |
+          python - <<'PY'
+          import glob, zipfile
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          assert not any(n.startswith("sillo/") for n in names), "wheel writes into sillo/"
+          print("wheel does not touch sillo/")
+          PY
+
+      # Prefers OIDC trusted publishing (the id-token permission above); falls
+      # back to an API token when the PYPI_TOKEN secret is set. Passing an empty
+      # --token is a hard failure, so the secret must not be forwarded blindly.
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          if [ -n "$PYPI_TOKEN" ]; then
+            uv publish --token "$PYPI_TOKEN"
+          else
+            uv publish
+          fi

sillo_wire-0.1.0.dev1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+
+.venv*/

sillo_wire-0.1.0.dev1/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.1.0.dev1
+
+Development pre-release for testing. Install with
+`pip install --pre sillo-wire==0.1.0.dev1`.
+
+First cut. Extracted from `sillo.websockets.channels` and rebuilt around
+three things the original could not do.
+
+### Added
+
+- `Hub` — rooms, membership and fan-out as an object rather than class methods
+  over a process-global dict. Two hubs are independent, which is what makes
+  tests and multi-tenancy straightforward.
+- `Peer` — a connection with a bounded outbound queue and its own writer task.
+- `Overflow` — `DROP_OLDEST`, `DROP_NEWEST` or `CLOSE` when a queue fills.
+- `DeliveryReport` — what a fan-out actually did, per peer.
+- `Envelope` — an immutable message carrying a monotonic sequence.
+- `Backlog` protocol, with `MemoryBacklog` and `NullBacklog`.
+- `Hub.replay` — send a reconnecting client only what it missed.
+- `Hub.send_to` — reach every connection an identity has open.
+- Presence: `on_join` / `on_leave` listeners, and `identities()` as a roster.
+- `RoomConsumer` — class-based endpoint with guaranteed cleanup.
+- `Hub.close` empties its rooms before awaiting anything and closes every peer
+  concurrently, so shutdown is not paced by the slowest socket.
+- `sillo.wire.testing` — `FakeSocket` and `drain` for testing realtime code.
+- Importable as both `sillo.wire` and `sillo_wire`. The alias is a
+  meta-path finder registered by a `.pth`, with PEP 561 partial stubs for
+  type checkers; nothing is written into the framework's own package.
+
+### Fixed, relative to the code this replaces
+
+- **A broadcast no longer blocks on the slowest client.** The previous fan-out
+  awaited each socket in turn, so one client that had stopped reading stalled
+  every other member of the group.
+- **The history cap now measures messages.** It previously sized the *list
+  object* with `sys.getsizeof`, so a 1 MB cap retained around 128 MB, and on
+  tripping discarded the entire history rather than the oldest part of it.
+- **Expiry distinguishes idle from lifetime.** Sending reset the creation time,
+  so a documented TTL behaved as an idle timeout without saying so.

sillo_wire-0.1.0.dev1/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-0.1.0.dev1/PKG-INFO

@@ -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.