tigrbl_engine_mempubsub 0.1.10.dev1__tar.gz

tigrbl_engine_mempubsub-0.1.10.dev1/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.nox/
+.venv/
+.coverage
+htmlcov/
+build/
+dist/
+site/
+target/
+*.egg-info/
+*.pyc
+*.zip
+/.vendor
+/.tmp
+*.body
+.pip-cache/
+*.pyd
+.tmp-release-plan-check.json

tigrbl_engine_mempubsub-0.1.10.dev1/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: tigrbl_engine_mempubsub
+Version: 0.1.10.dev1
+Requires-Python: <3.14,>=3.10
+Requires-Dist: tigrbl

tigrbl_engine_mempubsub-0.1.10.dev1/README.md

@@ -0,0 +1,23 @@
+# tigrbl_engine_mempubsub
+
+This file is a package-local distribution entry point.
+It is not the authoritative location for repository governance, current target status, current state reporting, certification claims, or release evidence.
+
+## Canonical repository docs
+
+- `README.md`
+- `docs/README.md`
+- `docs/conformance/CURRENT_TARGET.md`
+- `docs/conformance/CURRENT_STATE.md`
+- `docs/conformance/NEXT_STEPS.md`
+- `docs/governance/DOC_POINTERS.md`
+- `docs/developer/PACKAGE_CATALOG.md`
+- `docs/developer/PACKAGE_LAYOUT.md`
+
+## Package identity
+
+- workspace path: `pkgs/engines/tigrbl_engine_mempubsub`
+- workspace class: engine package
+- implementation layout: `src/tigrbl_engine_mempubsub/`
+
+Long-form repository documentation is governed from `docs/`.

tigrbl_engine_mempubsub-0.1.10.dev1/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tigrbl_engine_mempubsub"
+version = "0.1.10.dev1"
+requires-python = ">=3.10,<3.14"
+dependencies = ["tigrbl"]
+
+[project.entry-points."tigrbl.engine"]
+mempubsub = "tigrbl_engine_mempubsub.plugin:register"
+
+[tool.uv.sources]
+tigrbl = { workspace = true }

tigrbl_engine_mempubsub-0.1.10.dev1/src/tigrbl_engine_mempubsub/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"

tigrbl_engine_mempubsub-0.1.10.dev1/src/tigrbl_engine_mempubsub/plugin.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from tigrbl.engine.registry import register_engine
+
+from .pubsub import PubSubHub
+from .session import PubSubSession, AsyncPubSubSession
+
+
+def register() -> None:
+    register_engine(kind="mempubsub", build=build_mempubsub, capabilities=capabilities)
+
+
+def capabilities() -> dict:
+    return {
+        "engine": "mempubsub",
+        "transactional": False,
+        "async_native": True,
+        "persistence": "process",
+        "features": {"topics", "fanout", "subscriptions"},
+    }
+
+
+def build_mempubsub(*, mapping=None, spec=None, dsn=None, **_) -> tuple[object, object]:
+    mapping = dict(mapping or {})
+    async_ = bool(getattr(spec, "async_", False))
+
+    max_backlog = int(mapping.get("max_backlog_per_sub", 1024))
+    drop_policy = str(mapping.get("drop_policy", "drop_old")).lower()
+    namespace = str(mapping.get("namespace", "default"))
+
+    engine = PubSubHub(max_backlog_per_sub=max_backlog, drop_policy=drop_policy, namespace=namespace)
+
+    if async_:
+        def sessionmaker():
+            return AsyncPubSubSession(engine)
+    else:
+        def sessionmaker():
+            return PubSubSession(engine)
+
+    return engine, sessionmaker

tigrbl_engine_mempubsub-0.1.10.dev1/src/tigrbl_engine_mempubsub/pubsub.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from threading import Condition, RLock
+from time import monotonic
+from typing import Any
+
+
+@dataclass
+class _Sub:
+    lock: RLock
+    cv: Condition
+    dq: deque[Any]
+    closed: bool = False
+
+
+class Subscription:
+    def __init__(self, hub: "PubSubHub", topic: str, sub: _Sub) -> None:
+        self._hub = hub
+        self._topic = topic
+        self._sub = sub
+        self._closed = False
+
+    def recv(self, timeout: float | None = None) -> Any | None:
+        if self._closed:
+            return None
+        deadline = None if timeout is None else (monotonic() + max(0.0, float(timeout)))
+        s = self._sub
+        with s.lock:
+            while not s.closed and not s.dq:
+                if deadline is None:
+                    s.cv.wait()
+                else:
+                    remain = deadline - monotonic()
+                    if remain <= 0:
+                        return None
+                    s.cv.wait(remain)
+            if not s.dq:
+                return None
+            return s.dq.popleft()
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._hub._unsubscribe(self._topic, self._sub)
+
+    @property
+    def topic(self) -> str:
+        return self._topic
+
+
+class PubSubHub:
+    """In-process pub/sub with fanout to per-subscriber queues."""
+
+    def __init__(self, *, max_backlog_per_sub: int = 1024, drop_policy: str = "drop_old", namespace: str = "default") -> None:
+        if max_backlog_per_sub <= 0:
+            raise ValueError("max_backlog_per_sub must be > 0")
+        drop_policy = (drop_policy or "drop_old").lower()
+        if drop_policy not in {"drop_old", "drop_new", "block"}:
+            raise ValueError("drop_policy must be drop_old|drop_new|block")
+        self.max_backlog_per_sub = int(max_backlog_per_sub)
+        self.drop_policy = drop_policy
+        self.namespace = namespace
+
+        self._lock = RLock()
+        self._topics: dict[str, set[_Sub]] = {}
+
+    def subscribe(self, topic: str) -> Subscription:
+        t = topic or "default"
+        sub_lock = RLock()
+        sub = _Sub(lock=sub_lock, cv=Condition(sub_lock), dq=deque())
+        with self._lock:
+            self._topics.setdefault(t, set()).add(sub)
+        return Subscription(self, t, sub)
+
+    def _unsubscribe(self, topic: str, sub: _Sub) -> None:
+        with self._lock:
+            s = self._topics.get(topic)
+            if not s:
+                return
+            s.discard(sub)
+            if not s:
+                self._topics.pop(topic, None)
+        with sub.lock:
+            sub.closed = True
+            sub.cv.notify_all()
+
+    def publish(self, topic: str, msg: Any, *, timeout: float | None = None) -> int:
+        t = topic or "default"
+        deadline = None if timeout is None else (monotonic() + max(0.0, float(timeout)))
+        with self._lock:
+            subs = list(self._topics.get(t, ()))
+        delivered = 0
+        for sub in subs:
+            with sub.lock:
+                if sub.closed:
+                    continue
+                if len(sub.dq) >= self.max_backlog_per_sub:
+                    if self.drop_policy == "drop_new":
+                        continue
+                    if self.drop_policy == "drop_old":
+                        sub.dq.popleft()
+                    else:  # block
+                        while not sub.closed and len(sub.dq) >= self.max_backlog_per_sub:
+                            if deadline is None:
+                                sub.cv.wait()
+                            else:
+                                remain = deadline - monotonic()
+                                if remain <= 0:
+                                    break
+                                sub.cv.wait(remain)
+                        if sub.closed or len(sub.dq) >= self.max_backlog_per_sub:
+                            continue
+                sub.dq.append(msg)
+                sub.cv.notify()
+                delivered += 1
+        return delivered
+
+    def topics(self) -> list[str]:
+        with self._lock:
+            return sorted(self._topics.keys())

tigrbl_engine_mempubsub-0.1.10.dev1/src/tigrbl_engine_mempubsub/session.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .pubsub import PubSubHub, Subscription
+
+
+class PubSubSession:
+    def __init__(self, engine: PubSubHub) -> None:
+        self._engine = engine
+        self._closed = False
+
+    def close(self) -> None:
+        self._closed = True
+
+    def publish(self, topic: str, msg: Any, *, timeout: float | None = None) -> int:
+        self._require_open()
+        return self._engine.publish(topic, msg, timeout=timeout)
+
+    def subscribe(self, topic: str) -> Subscription:
+        self._require_open()
+        return self._engine.subscribe(topic)
+
+    def topics(self) -> list[str]:
+        self._require_open()
+        return self._engine.topics()
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("session is closed")
+
+
+class AsyncPubSubSession(PubSubSession):
+    async def close(self) -> None:  # type: ignore[override]
+        super().close()