tigrbl_engine_memrate 0.1.10.dev1__tar.gz

tigrbl_engine_memrate-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_memrate-0.1.10.dev1/PKG-INFO

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

tigrbl_engine_memrate-0.1.10.dev1/README.md

@@ -0,0 +1,23 @@
+# tigrbl_engine_memrate
+
+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_memrate`
+- workspace class: engine package
+- implementation layout: `src/tigrbl_engine_memrate/`
+
+Long-form repository documentation is governed from `docs/`.

tigrbl_engine_memrate-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_memrate"
+version = "0.1.10.dev1"
+requires-python = ">=3.10,<3.14"
+dependencies = ["tigrbl"]
+
+[project.entry-points."tigrbl.engine"]
+memrate = "tigrbl_engine_memrate.plugin:register"
+
+[tool.uv.sources]
+tigrbl = { workspace = true }

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

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

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

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from tigrbl.engine.registry import register_engine
+
+from .rate import RateLimiter
+from .session import RateSession, AsyncRateSession
+
+
+def register() -> None:
+    register_engine(kind="memrate", build=build_memrate, capabilities=capabilities)
+
+
+def capabilities() -> dict:
+    return {
+        "engine": "memrate",
+        "transactional": False,
+        "async_native": True,
+        "persistence": "process",
+        "features": {"token_bucket", "reserve"},
+    }
+
+
+def build_memrate(*, mapping=None, spec=None, dsn=None, **_) -> tuple[object, object]:
+    mapping = dict(mapping or {})
+    async_ = bool(getattr(spec, "async_", False))
+
+    rate_per_s = float(mapping.get("rate_per_s", 10.0))
+    burst = float(mapping.get("burst", max(1.0, rate_per_s)))
+    shards = int(mapping.get("shards", 64))
+    namespace = str(mapping.get("namespace", "default"))
+
+    engine = RateLimiter(
+        rate_per_s=rate_per_s,
+        burst=burst,
+        shards=shards,
+        namespace=namespace,
+    )
+
+    if async_:
+        def sessionmaker():
+            return AsyncRateSession(engine)
+    else:
+        def sessionmaker():
+            return RateSession(engine)
+
+    return engine, sessionmaker

tigrbl_engine_memrate-0.1.10.dev1/src/tigrbl_engine_memrate/rate.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from threading import RLock
+from time import monotonic
+from typing import Any
+
+
+@dataclass
+class _Bucket:
+    tokens: float
+    t_last: float
+
+
+class RateLimiter:
+    """Token-bucket limiter: allow/reserve by arbitrary key.
+
+    Semantics:
+      - rate_per_s: refill rate
+      - burst: max tokens
+      - cost: tokens consumed per request
+      - allow() returns bool
+      - reserve() returns wait_s (0 if immediate) or None if impossible (cost > burst)
+    """
+
+    def __init__(self, *, rate_per_s: float, burst: float, shards: int = 64, namespace: str = "default") -> None:
+        if rate_per_s <= 0:
+            raise ValueError("rate_per_s must be > 0")
+        if burst <= 0:
+            raise ValueError("burst must be > 0")
+        if shards <= 0:
+            raise ValueError("shards must be > 0")
+        self.rate_per_s = float(rate_per_s)
+        self.burst = float(burst)
+        self.shards = int(shards)
+        self.namespace = namespace
+
+        self._locks = [RLock() for _ in range(self.shards)]
+        self._maps: list[dict[str, _Bucket]] = [dict() for _ in range(self.shards)]
+
+    def _idx(self, key: str) -> int:
+        # deterministic per-process; good enough for sharding
+        return (hash((self.namespace, key)) & 0x7FFFFFFF) % self.shards
+
+    def _refill(self, b: _Bucket, now: float) -> None:
+        dt = now - b.t_last
+        if dt <= 0:
+            return
+        b.tokens = min(self.burst, b.tokens + dt * self.rate_per_s)
+        b.t_last = now
+
+    def _get_bucket(self, m: dict[str, _Bucket], key: str, now: float) -> _Bucket:
+        b = m.get(key)
+        if b is None:
+            b = _Bucket(tokens=self.burst, t_last=now)
+            m[key] = b
+        return b
+
+    def allow(self, key: str, *, cost: float = 1.0) -> bool:
+        wait = self.reserve(key, cost=cost)
+        return wait == 0.0
+
+    def reserve(self, key: str, *, cost: float = 1.0) -> float | None:
+        """Reserve tokens; returns wait seconds if not immediately available.
+
+        - If cost > burst, returns None (impossible).
+        - Otherwise deducts immediately if available; else returns required wait time WITHOUT deducting.
+          Caller may sleep and retry, or use wait to schedule.
+        """
+        if cost <= 0:
+            return 0.0
+        if cost > self.burst:
+            return None
+
+        now = monotonic()
+        i = self._idx(key)
+        with self._locks[i]:
+            m = self._maps[i]
+            b = self._get_bucket(m, key, now)
+            self._refill(b, now)
+            if b.tokens >= cost:
+                b.tokens -= cost
+                return 0.0
+            deficit = cost - b.tokens
+            # time until enough tokens accumulate
+            wait_s = deficit / self.rate_per_s
+            return max(0.0, wait_s)
+
+    def stats(self, key: str) -> dict[str, Any]:
+        now = monotonic()
+        i = self._idx(key)
+        with self._locks[i]:
+            m = self._maps[i]
+            b = self._get_bucket(m, key, now)
+            self._refill(b, now)
+            return {
+                "key": key,
+                "tokens": b.tokens,
+                "burst": self.burst,
+                "rate_per_s": self.rate_per_s,
+            }

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

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from .rate import RateLimiter
+
+
+class RateSession:
+    def __init__(self, engine: RateLimiter) -> None:
+        self._engine = engine
+        self._closed = False
+
+    def close(self) -> None:
+        self._closed = True
+
+    def allow(self, key: str, *, cost: float = 1.0) -> bool:
+        self._require_open()
+        return self._engine.allow(key, cost=cost)
+
+    def reserve(self, key: str, *, cost: float = 1.0) -> float | None:
+        self._require_open()
+        return self._engine.reserve(key, cost=cost)
+
+    def stats(self, key: str) -> dict:
+        self._require_open()
+        return self._engine.stats(key)
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("session is closed")
+
+
+class AsyncRateSession(RateSession):
+    async def close(self) -> None:  # type: ignore[override]
+        super().close()