roomer-client 0.1.0__tar.gz

roomer_client-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Rust build artifacts
+target/
+**/target/
+**/*.rs.bk
+*.rlib
+
+# Go build artifacts & binaries
+server_bin
+/app/server_bin
+bin/
+**/bin/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+*.prof
+
+# Node / Web / Package managers (if any tooling is added)
+node_modules/
+dist/
+.npm
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# IDEs and Text Editors
+.vscode/
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.idea/
+*.iml
+*.sublime-workspace
+*.sublime-project
+*.swp
+*.swo
+*~
+
+# Operating System Files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Environment variables & local overrides
+.env
+.env.local
+.env.*.local
+docker-compose.override.yml
+
+# TLA+ Model Checker (TLC) generated artifacts
+spec/states/
+MC.*
+*.tla.dump

roomer_client-0.1.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.5
+Name: roomer-client
+Version: 0.1.0
+Summary: High-performance, room-based WebSocket client for Roomer with binary framing and presence synchronization
+Author: Jon Cody
+License-Expression: MIT
+Keywords: asyncio,binary,clustering,realtime,rooms,websocket
+Requires-Python: >=3.10
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# `roomer-client` – Python Client SDK
+
+[![PyPI Version](https://img.shields.io/pypi/v/roomer-client.svg?color=3776AB&logo=pypi&logoColor=white)](https://pypi.org/project/roomer-client/)
+[![Python Version](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/)
+[![AsyncIO](https://img.shields.io/badge/AsyncIO-Native-00599C?style=flat&logo=python&logoColor=white)](https://docs.python.org/3/library/asyncio.html)
+[![Typing: Typed](https://img.shields.io/badge/Typing-PEP%20484%20%2F%20561-blue?style=flat)](https://peps.python.org/pep-0561/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+High-performance, asynchronous Python client for the Roomer WebSocket framework with zero-copy binary framing, automatic exponential reconnection with jitter, cluster-wide presence synchronization, and 100% wire protocol parity across Go, Rust, and Node.js servers.
+
+> 📖 **For Wire Protocol specifications and Server documentation, see the [Root README](../../README.md).**
+
+---
+
+## 📦 Scope & Architecture
+
+The `roomer-client` library provides an asynchronous, non-blocking interface for Python applications (FastAPI backends, AI/LLM streaming pipelines, data processing workers, CLI tools) to communicate over Roomer clusters.
+
+```text
+               +---------------------------------------------------+
+               |               Python Application                  |
+               |     (FastAPI / LangChain / PyTorch Worker)        |
+               +-------------------------+-------------------------+
+                                         |
+               +-------------------------v-------------------------+
+               |               Roomer Client SDK                   |
+               |  - asyncio / websockets async connection manager  |
+               |  - Async / Sync Dual-Mode Event Emitter           |
+               +-------------------+-------------------+-----------+
+                                   |                   |
+                     +-------------v----+        +-----v-------------+
+                     | Room Multiplexer |        | Binary Wire Frame |
+                     | (Presence & Acks)|        | (struct.pack >I)  |
+                     +------------------+        +-------------------+
+                                   |                   |
+               +-------------------v-------------------v-----------+
+               |              WebSocket Connection                 |
+               |     (Auto-Reconnect with Exponential Jitter)      |
+               +---------------------------------------------------+
+```
+
+---
+
+## ⚡ Key Features
+
+- **High-Performance Binary Wire Framing**: Serializes and unpacks 5 big-endian length-prefixed fields via native `struct.pack(">I", ...)` with zero-copy `memoryview` slicing.
+- **Dual-Mode Event Emitter**: Register event listeners as either standard synchronous functions (`def handler(...)`) or native coroutines (`async def handler(...)`).
+- **Async Context Manager**: Native `async with roomer("ws://...") as root:` pattern for deterministic lifecycle management and cleanup.
+- **Automatic Exponential Reconnection**: Recovers from abrupt socket disconnects with randomized jitter backoff while preserving room subscriptions across reconnects.
+- **Cluster Presence Tracking**: Automatic handling of `join_ack` snapshots, `new_member` notifications, and `member_left` presence events.
+- **Direct 1-to-1 Point-to-Point Unicast**: Route messages directly to specific client UUIDs across cluster nodes with $O(1)$ efficiency.
+
+---
+
+## 🚀 Installation
+
+Install from PyPI:
+
+```bash
+pip install roomer-client
+```
+
+Or install in editable mode for local development:
+
+```bash
+cd client/python
+pip install -e ".[dev]"
+```
+
+---
+
+## 🧠 Quick Start
+
+```python
+import asyncio
+from roomer import roomer
+
+async def main():
+    # Connect and auto-join the root room
+    async with roomer("ws://localhost:8080/ws") as root:
+        print(f"Connected to Roomer cluster! Client ID: {root.id}")
+
+        # Join a named room channel
+        lobby = root.join("lobby")
+
+        @lobby.on("open")
+        def on_open():
+            print(f"Joined lobby! Active members: {lobby.members()}")
+            lobby.send("chat", "Hello from Python!")
+
+        @lobby.on("chat")
+        def on_chat(payload: bytes, sender_id: str):
+            print(f"[{sender_id}]: {payload.decode('utf-8')}")
+
+        @lobby.on("new_member")
+        def on_new_member(member_id: str):
+            print(f"User joined lobby: {member_id}")
+
+        @lobby.on("member_left")
+        def on_member_left(member_id: str):
+            print(f"User left lobby: {member_id}")
+
+        # Keep running
+        await asyncio.Event().wait()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🛠️ Real-World Recipes & Patterns
+
+### 1. Streaming AI / LLM Tokens into a Room
+Stream token completions from OpenAI, Anthropic, or local HuggingFace/vLLM models in real-time to all clients subscribed to a room:
+
+```python
+import asyncio
+from roomer import roomer
+
+async def stream_ai_response(prompt: str, room_name: str):
+    async with roomer("ws://localhost:8080/ws") as root:
+        ai_room = root.join(room_name)
+
+        # Simulated token generator (e.g. from vLLM or Ollama)
+        tokens = ["The", " future", " of", " real-time", " messaging", " is", " binary."]
+        
+        for token in tokens:
+            ai_room.send("ai_token", token)
+            await asyncio.sleep(0.040)  # 40ms token interval
+
+        ai_room.send("ai_complete", {"prompt": prompt, "status": "done"})
+
+asyncio.run(stream_ai_response("Explain binary framing", "generation-101"))
+```
+
+---
+
+### 2. FastAPI Background Task Bridge
+Publish real-time telemetry, job notifications, or database changes from a FastAPI backend to connected browser clients:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, BackgroundTasks
+from roomer import RoomerClient
+
+client = RoomerClient("ws://localhost:8080/ws")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Connect Roomer client on FastAPI startup
+    await client.connect()
+    yield
+    # Gracefully close on shutdown
+    await client.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/notifications/broadcast")
+async def notify_users(message: str, background_tasks: BackgroundTasks):
+    def send_broadcast():
+        alerts_room = client.get_room("system-alerts")
+        alerts_room.send("alert", {"message": message, "severity": "info"})
+
+    background_tasks.add_task(send_broadcast)
+    return {"status": "broadcast scheduled"}
+```
+
+---
+
+### 3. Targeted 1-to-1 Direct Unicast
+Send direct private messages targeted at a specific client ID without broadcasting to the entire room:
+
+```python
+import asyncio
+from roomer import roomer
+
+async def main():
+    async with roomer("ws://localhost:8080/ws") as root:
+        target_client_id = "038edeb7-7823-4537-92c0-ba479cc2329c"
+
+        @root.on("direct_message")
+        def on_dm(payload: bytes, sender_id: str):
+            print(f"[Private DM from {sender_id}]: {payload.decode('utf-8')}")
+
+        # Send direct point-to-point packet (dst=target_client_id)
+        root.send("direct_message", "Secret private message", dst=target_client_id)
+        
+        await asyncio.sleep(2)
+
+asyncio.run(main())
+```
+
+---
+
+### 4. Custom Reconnection Backoff Configuration
+Fine-tune initial delay, backoff multiplier, and max backoff ceiling:
+
+```python
+from roomer import roomer
+
+# Configured for high-resilience environments
+root_context = roomer(
+    "ws://localhost:8080/ws",
+    reconnect=True,
+    initial_delay=0.250,   # Start at 250ms backoff
+    max_delay=10.0,        # Max backoff ceiling of 10s
+    backoff_factor=2.0     # Double backoff duration on consecutive drops
+)
+```
+
+---
+
+## 📚 API Reference
+
+### `roomer(url, **kwargs) -> RoomerContext`
+Factory function creating an asynchronous context manager.
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `url` | `str` | *Required* | WebSocket endpoint URL (e.g. `ws://localhost:8080/ws`). |
+| `reconnect` | `bool` | `True` | Automatically reconnect on connection drop. |
+| `initial_delay` | `float` | `0.5` | Initial backoff delay in seconds. |
+| `max_delay` | `float` | `5.0` | Maximum reconnection delay ceiling in seconds. |
+| `backoff_factor` | `float` | `1.5` | Backoff multiplier applied on consecutive failures. |
+
+---
+
+### `Room` Instance Properties & Methods
+
+#### Properties
+- **`room.name -> str`**: Channel name for this room instance.
+- **`room.id -> str`**: Assigned connection UUID string.
+- **`room.is_open -> bool`**: Returns `True` if room subscription is active.
+
+#### Methods
+| Method | Returns | Description |
+|---|---|---|
+| `room.members()` | `list[str]` | Shallow copy array of active member connection IDs. |
+| `room.join(room_name)` | `Room` | Subscribes to another room channel over the active connection. |
+| `room.leave()` | `Room` | Unsubscribes from the room and notifies the cluster. |
+| `room.send(event, payload=None, dst="")` | `Room` | Sends a message packet to the room or directly to `dst`. |
+| `room.on(event, listener)` | `Callable` | Subscribes a synchronous or asynchronous callback. Supports `@room.on(event)`. |
+| `room.once(event, listener)` | `Callable` | Subscribes a one-time event callback. |
+| `room.off(event, listener)` | `None` | Unsubscribes a registered listener callback. |
+| `room.clear_listeners(exceptions=None)` | `Room` | Clears custom listeners except those listed in `exceptions`. |
+| `room.force_close(is_disconnect=False)` | `Room` | Clears local member state and emits `"close"`. |
+| `root.purge()` *(root only)* | `Room` | Unsubscribes from all non-root rooms simultaneously. |
+| `root.rooms()` *(root only)* | `dict[str, Room]` | Dictionary mapping of all active room handles. |
+
+---
+
+### `Packet` Data Attributes & Helpers
+
+Decoded binary packet object passed into event handlers:
+
+| Attribute / Helper | Type | Description |
+|---|---|---|
+| `packet.room` | `str` | Target channel / room name. |
+| `packet.event` | `str` | Event descriptor string. |
+| `packet.dst` | `str` | Destination member ID (empty string if room broadcast). |
+| `packet.src` | `str` | Sender client ID. |
+| `packet.payload` | `bytes` | Raw binary payload bytes. |
+| `packet.payload_text()` | `str` | Decodes payload as UTF-8 string. |
+| `packet.payload_json()` | `Any` | Unmarshals binary payload as JSON. |
+
+---
+
+## 🧪 Testing & Verification
+
+Run the test suite using `pytest`:
+
+```bash
+cd client/python
+pip install -e ".[dev]"
+pytest -v
+```
+
+---
+
+## 📄 License
+
+Roomer is open-source software licensed under the [MIT License](../../LICENSE).

roomer_client-0.1.0/README.md

@@ -0,0 +1,283 @@
+# `roomer-client` – Python Client SDK
+
+[![PyPI Version](https://img.shields.io/pypi/v/roomer-client.svg?color=3776AB&logo=pypi&logoColor=white)](https://pypi.org/project/roomer-client/)
+[![Python Version](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/)
+[![AsyncIO](https://img.shields.io/badge/AsyncIO-Native-00599C?style=flat&logo=python&logoColor=white)](https://docs.python.org/3/library/asyncio.html)
+[![Typing: Typed](https://img.shields.io/badge/Typing-PEP%20484%20%2F%20561-blue?style=flat)](https://peps.python.org/pep-0561/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+High-performance, asynchronous Python client for the Roomer WebSocket framework with zero-copy binary framing, automatic exponential reconnection with jitter, cluster-wide presence synchronization, and 100% wire protocol parity across Go, Rust, and Node.js servers.
+
+> 📖 **For Wire Protocol specifications and Server documentation, see the [Root README](../../README.md).**
+
+---
+
+## 📦 Scope & Architecture
+
+The `roomer-client` library provides an asynchronous, non-blocking interface for Python applications (FastAPI backends, AI/LLM streaming pipelines, data processing workers, CLI tools) to communicate over Roomer clusters.
+
+```text
+               +---------------------------------------------------+
+               |               Python Application                  |
+               |     (FastAPI / LangChain / PyTorch Worker)        |
+               +-------------------------+-------------------------+
+                                         |
+               +-------------------------v-------------------------+
+               |               Roomer Client SDK                   |
+               |  - asyncio / websockets async connection manager  |
+               |  - Async / Sync Dual-Mode Event Emitter           |
+               +-------------------+-------------------+-----------+
+                                   |                   |
+                     +-------------v----+        +-----v-------------+
+                     | Room Multiplexer |        | Binary Wire Frame |
+                     | (Presence & Acks)|        | (struct.pack >I)  |
+                     +------------------+        +-------------------+
+                                   |                   |
+               +-------------------v-------------------v-----------+
+               |              WebSocket Connection                 |
+               |     (Auto-Reconnect with Exponential Jitter)      |
+               +---------------------------------------------------+
+```
+
+---
+
+## ⚡ Key Features
+
+- **High-Performance Binary Wire Framing**: Serializes and unpacks 5 big-endian length-prefixed fields via native `struct.pack(">I", ...)` with zero-copy `memoryview` slicing.
+- **Dual-Mode Event Emitter**: Register event listeners as either standard synchronous functions (`def handler(...)`) or native coroutines (`async def handler(...)`).
+- **Async Context Manager**: Native `async with roomer("ws://...") as root:` pattern for deterministic lifecycle management and cleanup.
+- **Automatic Exponential Reconnection**: Recovers from abrupt socket disconnects with randomized jitter backoff while preserving room subscriptions across reconnects.
+- **Cluster Presence Tracking**: Automatic handling of `join_ack` snapshots, `new_member` notifications, and `member_left` presence events.
+- **Direct 1-to-1 Point-to-Point Unicast**: Route messages directly to specific client UUIDs across cluster nodes with $O(1)$ efficiency.
+
+---
+
+## 🚀 Installation
+
+Install from PyPI:
+
+```bash
+pip install roomer-client
+```
+
+Or install in editable mode for local development:
+
+```bash
+cd client/python
+pip install -e ".[dev]"
+```
+
+---
+
+## 🧠 Quick Start
+
+```python
+import asyncio
+from roomer import roomer
+
+async def main():
+    # Connect and auto-join the root room
+    async with roomer("ws://localhost:8080/ws") as root:
+        print(f"Connected to Roomer cluster! Client ID: {root.id}")
+
+        # Join a named room channel
+        lobby = root.join("lobby")
+
+        @lobby.on("open")
+        def on_open():
+            print(f"Joined lobby! Active members: {lobby.members()}")
+            lobby.send("chat", "Hello from Python!")
+
+        @lobby.on("chat")
+        def on_chat(payload: bytes, sender_id: str):
+            print(f"[{sender_id}]: {payload.decode('utf-8')}")
+
+        @lobby.on("new_member")
+        def on_new_member(member_id: str):
+            print(f"User joined lobby: {member_id}")
+
+        @lobby.on("member_left")
+        def on_member_left(member_id: str):
+            print(f"User left lobby: {member_id}")
+
+        # Keep running
+        await asyncio.Event().wait()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🛠️ Real-World Recipes & Patterns
+
+### 1. Streaming AI / LLM Tokens into a Room
+Stream token completions from OpenAI, Anthropic, or local HuggingFace/vLLM models in real-time to all clients subscribed to a room:
+
+```python
+import asyncio
+from roomer import roomer
+
+async def stream_ai_response(prompt: str, room_name: str):
+    async with roomer("ws://localhost:8080/ws") as root:
+        ai_room = root.join(room_name)
+
+        # Simulated token generator (e.g. from vLLM or Ollama)
+        tokens = ["The", " future", " of", " real-time", " messaging", " is", " binary."]
+        
+        for token in tokens:
+            ai_room.send("ai_token", token)
+            await asyncio.sleep(0.040)  # 40ms token interval
+
+        ai_room.send("ai_complete", {"prompt": prompt, "status": "done"})
+
+asyncio.run(stream_ai_response("Explain binary framing", "generation-101"))
+```
+
+---
+
+### 2. FastAPI Background Task Bridge
+Publish real-time telemetry, job notifications, or database changes from a FastAPI backend to connected browser clients:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, BackgroundTasks
+from roomer import RoomerClient
+
+client = RoomerClient("ws://localhost:8080/ws")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Connect Roomer client on FastAPI startup
+    await client.connect()
+    yield
+    # Gracefully close on shutdown
+    await client.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/notifications/broadcast")
+async def notify_users(message: str, background_tasks: BackgroundTasks):
+    def send_broadcast():
+        alerts_room = client.get_room("system-alerts")
+        alerts_room.send("alert", {"message": message, "severity": "info"})
+
+    background_tasks.add_task(send_broadcast)
+    return {"status": "broadcast scheduled"}
+```
+
+---
+
+### 3. Targeted 1-to-1 Direct Unicast
+Send direct private messages targeted at a specific client ID without broadcasting to the entire room:
+
+```python
+import asyncio
+from roomer import roomer
+
+async def main():
+    async with roomer("ws://localhost:8080/ws") as root:
+        target_client_id = "038edeb7-7823-4537-92c0-ba479cc2329c"
+
+        @root.on("direct_message")
+        def on_dm(payload: bytes, sender_id: str):
+            print(f"[Private DM from {sender_id}]: {payload.decode('utf-8')}")
+
+        # Send direct point-to-point packet (dst=target_client_id)
+        root.send("direct_message", "Secret private message", dst=target_client_id)
+        
+        await asyncio.sleep(2)
+
+asyncio.run(main())
+```
+
+---
+
+### 4. Custom Reconnection Backoff Configuration
+Fine-tune initial delay, backoff multiplier, and max backoff ceiling:
+
+```python
+from roomer import roomer
+
+# Configured for high-resilience environments
+root_context = roomer(
+    "ws://localhost:8080/ws",
+    reconnect=True,
+    initial_delay=0.250,   # Start at 250ms backoff
+    max_delay=10.0,        # Max backoff ceiling of 10s
+    backoff_factor=2.0     # Double backoff duration on consecutive drops
+)
+```
+
+---
+
+## 📚 API Reference
+
+### `roomer(url, **kwargs) -> RoomerContext`
+Factory function creating an asynchronous context manager.
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `url` | `str` | *Required* | WebSocket endpoint URL (e.g. `ws://localhost:8080/ws`). |
+| `reconnect` | `bool` | `True` | Automatically reconnect on connection drop. |
+| `initial_delay` | `float` | `0.5` | Initial backoff delay in seconds. |
+| `max_delay` | `float` | `5.0` | Maximum reconnection delay ceiling in seconds. |
+| `backoff_factor` | `float` | `1.5` | Backoff multiplier applied on consecutive failures. |
+
+---
+
+### `Room` Instance Properties & Methods
+
+#### Properties
+- **`room.name -> str`**: Channel name for this room instance.
+- **`room.id -> str`**: Assigned connection UUID string.
+- **`room.is_open -> bool`**: Returns `True` if room subscription is active.
+
+#### Methods
+| Method | Returns | Description |
+|---|---|---|
+| `room.members()` | `list[str]` | Shallow copy array of active member connection IDs. |
+| `room.join(room_name)` | `Room` | Subscribes to another room channel over the active connection. |
+| `room.leave()` | `Room` | Unsubscribes from the room and notifies the cluster. |
+| `room.send(event, payload=None, dst="")` | `Room` | Sends a message packet to the room or directly to `dst`. |
+| `room.on(event, listener)` | `Callable` | Subscribes a synchronous or asynchronous callback. Supports `@room.on(event)`. |
+| `room.once(event, listener)` | `Callable` | Subscribes a one-time event callback. |
+| `room.off(event, listener)` | `None` | Unsubscribes a registered listener callback. |
+| `room.clear_listeners(exceptions=None)` | `Room` | Clears custom listeners except those listed in `exceptions`. |
+| `room.force_close(is_disconnect=False)` | `Room` | Clears local member state and emits `"close"`. |
+| `root.purge()` *(root only)* | `Room` | Unsubscribes from all non-root rooms simultaneously. |
+| `root.rooms()` *(root only)* | `dict[str, Room]` | Dictionary mapping of all active room handles. |
+
+---
+
+### `Packet` Data Attributes & Helpers
+
+Decoded binary packet object passed into event handlers:
+
+| Attribute / Helper | Type | Description |
+|---|---|---|
+| `packet.room` | `str` | Target channel / room name. |
+| `packet.event` | `str` | Event descriptor string. |
+| `packet.dst` | `str` | Destination member ID (empty string if room broadcast). |
+| `packet.src` | `str` | Sender client ID. |
+| `packet.payload` | `bytes` | Raw binary payload bytes. |
+| `packet.payload_text()` | `str` | Decodes payload as UTF-8 string. |
+| `packet.payload_json()` | `Any` | Unmarshals binary payload as JSON. |
+
+---
+
+## 🧪 Testing & Verification
+
+Run the test suite using `pytest`:
+
+```bash
+cd client/python
+pip install -e ".[dev]"
+pytest -v
+```
+
+---
+
+## 📄 License
+
+Roomer is open-source software licensed under the [MIT License](../../LICENSE).

roomer_client-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roomer-client"
+version = "0.1.0"
+description = "High-performance, room-based WebSocket client for Roomer with binary framing and presence synchronization"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Jon Cody" }
+]
+requires-python = ">=3.10"
+keywords = [
+    "websocket",
+    "realtime",
+    "rooms",
+    "binary",
+    "asyncio",
+    "clustering"
+]
+dependencies = [
+    "websockets>=12.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23"
+]
+
+[tool.hatch.build.targets.wheel]
+include = [
+    "roomer.py",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "roomer.py",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

roomer_client-0.1.0/roomer.py

@@ -0,0 +1,565 @@
+"""
+Roomer Python Client SDK.
+
+High-performance, room-based WebSocket client with zero-copy binary framing,
+exponential reconnection with jitter, presence synchronization, and full parity
+with Go, Rust, and Node.js servers.
+
+License: MIT
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import random
+import struct
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import websockets
+
+HEADER_OVERHEAD: int = 20
+
+RESERVED_EVENTS: frozenset[str] = frozenset({
+    "close",
+    "join",
+    "join_ack",
+    "leave",
+    "leave_ack",
+    "member_left",
+    "new_member",
+    "open"
+})
+
+Listener = Callable[..., Any]
+
+
+# ==============================================================================
+# 1. Wire Protocol & Binary Framing
+# ==============================================================================
+
+@dataclass(frozen=True, slots=True)
+class Packet:
+    """Represents an immutable decoded Roomer binary wire frame."""
+    room: str
+    event: str
+    dst: str
+    src: str
+    payload: bytes
+
+    def payload_text(self, encoding: str = "utf-8") -> str:
+        """Decodes the binary payload as a text string."""
+        return self.payload.decode(encoding)
+
+    def payload_json(self) -> Any:
+        """Parses the binary payload as JSON."""
+        if not self.payload:
+            raise ValueError("Payload is empty")
+        return json.loads(self.payload.decode("utf-8"))
+
+
+def encode_message(
+    room: str = "",
+    event: str = "",
+    dst: str = "",
+    src: str = "",
+    payload: bytes | bytearray | memoryview | str | dict | list | int | float | bool | None = None
+) -> bytes:
+    """
+    Serializes message parameters into a contiguous big-endian length-prefixed binary packet.
+    Format: [4B room_len][room][4B event_len][event][4B dst_len][dst][4B src_len][src][4B payload_len][payload]
+    """
+    room_bytes = room.encode("utf-8") if isinstance(room, str) else b""
+    event_bytes = event.encode("utf-8") if isinstance(event, str) else b""
+    dst_bytes = dst.encode("utf-8") if isinstance(dst, str) else b""
+    src_bytes = src.encode("utf-8") if isinstance(src, str) else b""
+
+    if payload is None:
+        payload_bytes = b""
+    elif isinstance(payload, bytes):
+        payload_bytes = payload
+    elif isinstance(payload, (bytearray, memoryview)):
+        payload_bytes = bytes(payload)
+    elif isinstance(payload, str):
+        payload_bytes = payload.encode("utf-8")
+    elif isinstance(payload, (dict, list)):
+        payload_bytes = json.dumps(payload).encode("utf-8")
+    elif isinstance(payload, (int, float, bool)):
+        payload_bytes = str(payload).encode("utf-8")
+    else:
+        payload_bytes = b""
+
+    fmt = f">I{len(room_bytes)}sI{len(event_bytes)}sI{len(dst_bytes)}sI{len(src_bytes)}sI{len(payload_bytes)}s"
+    return struct.pack(
+        fmt,
+        len(room_bytes),
+        room_bytes,
+        len(event_bytes),
+        event_bytes,
+        len(dst_bytes),
+        dst_bytes,
+        len(src_bytes),
+        src_bytes,
+        len(payload_bytes),
+        payload_bytes
+    )
+
+
+def decode_message(data: bytes | bytearray | memoryview) -> Packet | None:
+    """
+    Decodes raw binary bytes into a Packet instance. Returns None on malformed input.
+    """
+    buf = memoryview(data)
+    if len(buf) < HEADER_OVERHEAD:
+        return None
+
+    offset = 0
+
+    try:
+        # 1. Room
+        (room_len,) = struct.unpack_from(">I", buf, offset)
+        offset += 4
+        if offset + room_len > len(buf):
+            return None
+        room = bytes(buf[offset : offset + room_len]).decode("utf-8")
+        offset += room_len
+
+        # 2. Event
+        if offset + 4 > len(buf):
+            return None
+        (event_len,) = struct.unpack_from(">I", buf, offset)
+        offset += 4
+        if offset + event_len > len(buf):
+            return None
+        event = bytes(buf[offset : offset + event_len]).decode("utf-8")
+        offset += event_len
+
+        # 3. Dst
+        if offset + 4 > len(buf):
+            return None
+        (dst_len,) = struct.unpack_from(">I", buf, offset)
+        offset += 4
+        if offset + dst_len > len(buf):
+            return None
+        dst = bytes(buf[offset : offset + dst_len]).decode("utf-8")
+        offset += dst_len
+
+        # 4. Src
+        if offset + 4 > len(buf):
+            return None
+        (src_len,) = struct.unpack_from(">I", buf, offset)
+        offset += 4
+        if offset + src_len > len(buf):
+            return None
+        src = bytes(buf[offset : offset + src_len]).decode("utf-8")
+        offset += src_len
+
+        # 5. Payload
+        if offset + 4 > len(buf):
+            return None
+        (payload_len,) = struct.unpack_from(">I", buf, offset)
+        offset += 4
+        if offset + payload_len != len(buf):
+            return None
+        payload = bytes(buf[offset : offset + payload_len])
+
+        return Packet(room=room, event=event, dst=dst, src=src, payload=payload)
+    except (struct.error, UnicodeDecodeError):
+        return None
+
+
+# ==============================================================================
+# 2. Async-Compatible Event Emitter
+# ==============================================================================
+
+class EventEmitter:
+    """Lightweight event emitter supporting both sync functions and async coroutines."""
+
+    def __init__(self) -> None:
+        self._events: dict[str, list[Listener]] = defaultdict(list)
+
+    def on(self, event: str, listener: Listener | None = None) -> Listener | Callable[[Listener], Listener]:
+        """Registers an event listener callback or decorator."""
+        def decorator(fn: Listener) -> Listener:
+            self._events[event].append(fn)
+            return fn
+
+        if listener is not None:
+            return decorator(listener)
+        return decorator
+
+    def once(self, event: str, listener: Listener | None = None) -> Listener | Callable[[Listener], Listener]:
+        """Registers a one-time event listener callback."""
+        def decorator(fn: Listener) -> Listener:
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                self.off(event, wrapper)
+                return fn(*args, **kwargs)
+
+            setattr(wrapper, "_original_fn", fn)
+            self._events[event].append(wrapper)
+            return fn
+
+        if listener is not None:
+            return decorator(listener)
+        return decorator
+
+    def off(self, event: str, listener: Listener) -> None:
+        """Removes a registered event listener callback."""
+        if event in self._events:
+            self._events[event] = [
+                fn for fn in self._events[event]
+                if fn != listener and getattr(fn, "_original_fn", None) != listener
+            ]
+            if not self._events[event]:
+                del self._events[event]
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> bool:
+        """Synchronously invokes listeners, dispatching coroutines to the event loop."""
+        listeners = list(self._events.get(event, []))
+        if not listeners:
+            return False
+
+        for fn in listeners:
+            try:
+                res = fn(*args, **kwargs)
+                if inspect.isawaitable(res):
+                    try:
+                        loop = asyncio.get_running_loop()
+                        loop.create_task(res)
+                    except RuntimeError:
+                        pass
+            except Exception as err:
+                print(f"[Roomer] Unhandled exception in listener for '{event}': {err}")
+
+        return True
+
+    def remove_all_listeners(self, event: str | None = None) -> None:
+        """Removes all registered listeners, or those for a specific event."""
+        if event is None:
+            self._events.clear()
+        elif event in self._events:
+            del self._events[event]
+
+    def listeners(self, event: str) -> list[Listener]:
+        """Returns a copy of registered listener callbacks for an event."""
+        return list(self._events.get(event, []))
+
+
+# ==============================================================================
+# 3. Room Channel Handle
+# ==============================================================================
+
+class Room(EventEmitter):
+    """Represents a room channel subscription over the WebSocket connection."""
+
+    def __init__(
+        self,
+        name: str,
+        send_packet_fn: Callable[[str, str, str, str, Any], None],
+        get_room_fn: Callable[[str], Room],
+        is_socket_open_fn: Callable[[], bool],
+    ) -> None:
+        super().__init__()
+        self.name = name
+        self._send_packet = send_packet_fn
+        self._get_room = get_room_fn
+        self._is_socket_open = is_socket_open_fn
+
+        self._member_id: str = ""
+        self._is_open: bool = False
+        self._members: list[str] = []
+        self._custom_events: set[str] = set()
+
+    @property
+    def id(self) -> str:
+        """Connection UUID string assigned by the server."""
+        return self._member_id
+
+    @property
+    def is_open(self) -> bool:
+        """Whether room membership is currently active."""
+        return self._is_open
+
+    def open(self) -> bool:
+        """Method alias for is_open."""
+        return self._is_open
+
+    def members(self) -> list[str]:
+        """Returns a shallow copy of active member IDs in this room."""
+        return list(self._members)
+
+    def join(self, room_name: str) -> Room:
+        """Subscribes to a new room channel over the existing connection."""
+        if not self._is_open:
+            raise RuntimeError("Cannot join: current room is closed.")
+        if not isinstance(room_name, str):
+            raise TypeError("Room name must be a string.")
+        return self._get_room(room_name)
+
+    def leave(self) -> Room:
+        """Leaves the current room and notifies the cluster."""
+        if not self._is_open:
+            raise RuntimeError("Cannot leave: room is closed.")
+        if self._is_socket_open():
+            self._send_packet(self.name, "leave", "", "", b"")
+        return self
+
+    def send(self, event: str, payload: Any = None, dst: str = "") -> Room:
+        """Sends an event message to the room or directly to a member ID."""
+        if not self._is_open:
+            raise RuntimeError("Cannot send: socket is closed.")
+        if not isinstance(event, str):
+            raise TypeError("Event name must be a string.")
+        if event in RESERVED_EVENTS:
+            raise ValueError(f"Cannot send reserved event: '{event}'")
+
+        if self._is_socket_open():
+            self._send_packet(self.name, event, dst, self._member_id, payload)
+        return self
+
+    def clear_listeners(self, exceptions: list[str] | set[str] | None = None) -> Room:
+        """Clears registered event listeners except those listed in exceptions."""
+        exc = set(exceptions or [])
+        for event_name in list(self._custom_events):
+            if event_name not in exc:
+                self.remove_all_listeners(event_name)
+                self._custom_events.discard(event_name)
+        return self
+
+    def force_close(self, is_disconnect: bool = False) -> Room:
+        """Closes the room locally and clears tracked state."""
+        if self._is_open:
+            self._is_open = False
+            self._members.clear()
+            self.emit("close")
+            if not is_disconnect:
+                self._member_id = ""
+        return self
+
+    def parse(self, packet: Packet) -> None:
+        """Dispatches an incoming parsed packet to room event listeners."""
+        match packet.event:
+            case "join_ack":
+                self._member_id = packet.src
+                self._members.clear()
+                try:
+                    parsed = json.loads(packet.payload_text())
+                    if isinstance(parsed, list):
+                        self._members.extend(str(m) for m in parsed)
+                except Exception:
+                    pass
+                self._is_open = True
+                self.emit("open")
+
+            case "new_member":
+                member_id = packet.payload_text()
+                if member_id and member_id not in self._members:
+                    self._members.append(member_id)
+                    self.emit("new_member", member_id)
+
+            case "leave_ack":
+                self.emit("close")
+                self._is_open = False
+                self._members.clear()
+                self._member_id = ""
+
+            case "member_left":
+                member_id = packet.payload_text()
+                if member_id in self._members:
+                    self._members.remove(member_id)
+                    self.emit("member_left", member_id)
+
+            case _:
+                self.emit(packet.event, packet.payload, packet.src)
+
+    def on(self, event: str, listener: Listener | None = None) -> Any:
+        if event not in RESERVED_EVENTS:
+            self._custom_events.add(event)
+        return super().on(event, listener)
+
+
+# ==============================================================================
+# 4. Connection Lifecycle & Context Manager
+# ==============================================================================
+
+class RoomerClient:
+    """Manages the underlying WebSocket connection and room multiplexing."""
+
+    def __init__(
+        self,
+        url: str,
+        reconnect: bool = True,
+        initial_delay: float = 0.5,
+        max_delay: float = 5.0,
+        backoff_factor: float = 1.5,
+    ) -> None:
+        if not isinstance(url, str):
+            raise TypeError("WebSocket URL must be a string.")
+
+        self.url = url
+        self.reconnect = reconnect
+        self.initial_delay = initial_delay
+        self.max_delay = max_delay
+        self.backoff_factor = backoff_factor
+
+        self._rooms: dict[str, Room] = {}
+        self._ws: Any = None
+        self._running: bool = False
+        self._manual_close: bool = False
+        self._task: asyncio.Task[None] | None = None
+        self._reconnect_delay: float = initial_delay
+
+        self._root = self.get_room("root")
+
+    @property
+    def root(self) -> Room:
+        """Returns the default 'root' room instance."""
+        return self._root
+
+    def get_room(self, name: str) -> Room:
+        """Retrieves or instantiates a room client interface by name."""
+        if not isinstance(name, str):
+            raise TypeError("Room name must be a string.")
+        if name in self._rooms:
+            return self._rooms[name]
+
+        room = Room(
+            name=name,
+            send_packet_fn=self._send_packet,
+            get_room_fn=self.get_room,
+            is_socket_open_fn=self.is_connected,
+        )
+
+        if name == "root":
+            def purge() -> Room:
+                for r_name in list(self._rooms.keys()):
+                    if r_name != "root":
+                        self._rooms[r_name].leave()
+                return room
+
+            def rooms_map() -> dict[str, Room]:
+                return dict(self._rooms)
+
+            setattr(room, "purge", purge)
+            setattr(room, "rooms", rooms_map)
+
+        self._rooms[name] = room
+
+        if name != "root" and self.is_connected():
+            self._send_packet(name, "join", "", "", b"")
+
+        return room
+
+    def is_connected(self) -> bool:
+        """Returns True if the underlying WebSocket connection is active."""
+        return self._ws is not None and not getattr(self._ws, "closed", False)
+
+    def _send_packet(
+        self,
+        room: str,
+        event: str,
+        dst: str,
+        src: str,
+        payload: Any
+    ) -> None:
+        """Serializes and transmits a binary frame over the WebSocket."""
+        if self.is_connected() and self._ws is not None:
+            raw = encode_message(room, event, dst, src, payload)
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._ws.send(raw))
+            except RuntimeError:
+                pass
+
+    async def connect(self) -> Room:
+        """Starts the background event loop and waits for root join_ack."""
+        if self._running:
+            return self._root
+
+        self._running = True
+        self._manual_close = False
+        self._task = asyncio.create_task(self._run_loop())
+
+        while self._running and not self._root.is_open:
+            await asyncio.sleep(0.010)
+
+        return self._root
+
+    async def _run_loop(self) -> None:
+        """Background connection supervisor with exponential backoff and jitter."""
+        while self._running:
+            try:
+                async with websockets.connect(self.url) as ws:
+                    self._ws = ws
+                    self._reconnect_delay = self.initial_delay
+
+                    # Re-join all non-root active rooms upon reconnection
+                    for r_name in list(self._rooms.keys()):
+                        if r_name != "root":
+                            raw = encode_message(r_name, "join", "", "", b"")
+                            await ws.send(raw)
+
+                    # Reader loop
+                    async for raw_message in ws:
+                        if isinstance(raw_message, (bytes, bytearray, memoryview)):
+                            packet = decode_message(raw_message)
+                            if packet is not None and packet.room in self._rooms:
+                                self._rooms[packet.room].parse(packet)
+
+            except (websockets.exceptions.WebSocketException, OSError, asyncio.CancelledError):
+                pass
+            finally:
+                self._ws = None
+                is_reconnecting = self.reconnect and not self._manual_close and self._running
+                for r in list(self._rooms.values()):
+                    r.force_close(is_disconnect=is_reconnecting)
+
+            if not self.reconnect or self._manual_close or not self._running:
+                break
+
+            jitter = random.uniform(0, 0.200)
+            await asyncio.sleep(self._reconnect_delay + jitter)
+            self._reconnect_delay = min(self._reconnect_delay * self.backoff_factor, self.max_delay)
+
+    async def close(self) -> None:
+        """Gracefully closes all rooms and the WebSocket connection."""
+        self._manual_close = True
+        self._running = False
+        if self._ws is not None:
+            await self._ws.close()
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        for r in list(self._rooms.values()):
+            r.force_close(is_disconnect=False)
+        self._rooms.clear()
+
+
+class RoomerContext:
+    """Async context manager wrapper for Roomer."""
+
+    def __init__(self, url: str, **kwargs: Any) -> None:
+        self.client = RoomerClient(url, **kwargs)
+
+    async def __aenter__(self) -> Room:
+        await self.client.connect()
+        return self.client.root
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.client.close()
+
+
+def roomer(url: str, **kwargs: Any) -> RoomerContext:
+    """
+    Initializes a Roomer client instance. Supports async context manager:
+    async with roomer("ws://localhost:8080/ws") as root:
+        lobby = root.join("lobby")
+    """
+    return RoomerContext(url, **kwargs)