tigrbl_engine_memrate 0.1.10.dev1__py3-none-any.whl

tigrbl_engine_memrate/__init__.py

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

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/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/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()

tigrbl_engine_memrate-0.1.10.dev1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+tigrbl_engine_memrate/__init__.py,sha256=tXbRXsO0NE_UV1kIHiZTTQQH0fj0U2KoxxNusu_gzrM,48
+tigrbl_engine_memrate/plugin.py,sha256=NkbCk78TUwNeeDLdkG2nALXJWBUOV17vR4ZU9vE70GA,1230
+tigrbl_engine_memrate/rate.py,sha256=UdESaSlW6CPIbCYAZIaO0v1XgRfSNLsZlNuDCh8PD0Q,3279
+tigrbl_engine_memrate/session.py,sha256=td_Q5rHDyA-NzS9nalG8MtfWhkUXLsaYi_n3Qn60zxo,898
+tigrbl_engine_memrate-0.1.10.dev1.dist-info/METADATA,sha256=mebBot6eunggwP6_wl47mkqgxjFB58DVQE-Cl5kdkrU,123
+tigrbl_engine_memrate-0.1.10.dev1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tigrbl_engine_memrate-0.1.10.dev1.dist-info/entry_points.txt,sha256=jnLamtkEei9oaiQ4C29cj6LdjZtVH0MyiUvYCrMpoNc,64
+tigrbl_engine_memrate-0.1.10.dev1.dist-info/RECORD,,

tigrbl_engine_memrate-0.1.10.dev1.dist-info/WHEEL

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

tigrbl_engine_memrate-0.1.10.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[tigrbl.engine]
+memrate = tigrbl_engine_memrate.plugin:register