tigrbl_engine_memkv 0.1.10.dev1__py3-none-any.whl

tigrbl_engine_memkv/__init__.py

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

tigrbl_engine_memkv/kv.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import heapq
+from dataclasses import dataclass
+from threading import RLock
+from time import monotonic
+from typing import Any, Iterable
+
+
+@dataclass(order=True)
+class _Exp:
+    expires_at: float
+    key: str
+    version: int
+
+
+@dataclass
+class _Val:
+    version: int
+    value: Any
+    expires_at: float | None
+
+
+class KVStore:
+    """Versioned in-memory KV with TTL and CAS.
+
+    Keyspace is namespaced at engine level.
+    TTL uses monotonic clock; cleanup is heap-based and amortized.
+    """
+
+    def __init__(self, *, namespace: str = "default", default_ttl_s: float | None = None, max_items: int = 1_000_000) -> None:
+        if max_items <= 0:
+            raise ValueError("max_items must be > 0")
+        if default_ttl_s is not None and default_ttl_s <= 0:
+            raise ValueError("default_ttl_s must be > 0 if set")
+        self.namespace = namespace
+        self.default_ttl_s = default_ttl_s
+        self.max_items = int(max_items)
+
+        self._lock = RLock()
+        self._m: dict[str, _Val] = {}
+        self._h: list[_Exp] = []
+
+    def _gc(self, now: float) -> None:
+        while self._h:
+            e = self._h[0]
+            if e.expires_at > now:
+                return
+            heapq.heappop(self._h)
+            cur = self._m.get(e.key)
+            if cur is None:
+                continue
+            # only evict if version matches and is actually expired
+            if cur.version == e.version and cur.expires_at is not None and cur.expires_at <= now:
+                self._m.pop(e.key, None)
+
+    def _set(self, key: str, value: Any, ttl_s: float | None) -> int:
+        now = monotonic()
+        with self._lock:
+            self._gc(now)
+            cur = self._m.get(key)
+            ver = 1 if cur is None else (cur.version + 1)
+            exp_at: float | None = None
+            if ttl_s is None:
+                ttl_s = self.default_ttl_s
+            if ttl_s is not None:
+                ttl = float(ttl_s)
+                if ttl <= 0:
+                    raise ValueError("ttl_s must be > 0 if set")
+                exp_at = now + ttl
+            self._m[key] = _Val(version=ver, value=value, expires_at=exp_at)
+            if exp_at is not None:
+                heapq.heappush(self._h, _Exp(exp_at, key, ver))
+            self._enforce_max(now)
+            return ver
+
+    def get(self, key: str, default: Any = None) -> Any:
+        now = monotonic()
+        with self._lock:
+            self._gc(now)
+            v = self._m.get(key)
+            if v is None:
+                return default
+            if v.expires_at is not None and v.expires_at <= now:
+                self._m.pop(key, None)
+                return default
+            return v.value
+
+    def get_version(self, key: str) -> int | None:
+        now = monotonic()
+        with self._lock:
+            self._gc(now)
+            v = self._m.get(key)
+            if v is None:
+                return None
+            if v.expires_at is not None and v.expires_at <= now:
+                self._m.pop(key, None)
+                return None
+            return v.version
+
+    def set(self, key: str, value: Any, *, ttl_s: float | None = None) -> int:
+        return self._set(key, value, ttl_s)
+
+    def cas(self, key: str, expected_version: int, value: Any, *, ttl_s: float | None = None) -> int | None:
+        now = monotonic()
+        with self._lock:
+            self._gc(now)
+            cur = self._m.get(key)
+            if cur is None:
+                return None
+            if cur.expires_at is not None and cur.expires_at <= now:
+                self._m.pop(key, None)
+                return None
+            if cur.version != int(expected_version):
+                return None
+        # perform write outside of read lock? keep simple: do within lock
+        with self._lock:
+            self._gc(monotonic())
+            cur2 = self._m.get(key)
+            if cur2 is None or cur2.version != int(expected_version):
+                return None
+            return self._set(key, value, ttl_s)
+
+    def delete(self, key: str) -> bool:
+        now = monotonic()
+        with self._lock:
+            self._gc(now)
+            return self._m.pop(key, None) is not None
+
+    def keys(self, prefix: str = "") -> list[str]:
+        now = monotonic()
+        with self._lock:
+            self._gc(now)
+            if not prefix:
+                return sorted(self._m.keys())
+            return sorted(k for k in self._m.keys() if k.startswith(prefix))
+
+    def reset(self) -> None:
+        with self._lock:
+            self._m.clear()
+            self._h.clear()
+
+    def stats(self) -> dict[str, Any]:
+        now = monotonic()
+        with self._lock:
+            self._gc(now)
+            return {"size": len(self._m), "max_items": self.max_items, "default_ttl_s": self.default_ttl_s}
+
+    def _enforce_max(self, now: float) -> None:
+        # Evict arbitrary oldest-expiring entries to enforce cap
+        while len(self._m) > self.max_items and self._h:
+            e = heapq.heappop(self._h)
+            self._m.pop(e.key, None)

tigrbl_engine_memkv/plugin.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from tigrbl.engine.registry import register_engine
+
+from .kv import KVStore
+from .session import KVSession, AsyncKVSession
+
+
+def register() -> None:
+    register_engine(kind="memkv", build=build_memkv, capabilities=capabilities)
+
+
+def capabilities() -> dict:
+    return {
+        "engine": "memkv",
+        "transactional": False,
+        "async_native": True,
+        "persistence": "process",
+        "features": {"kv", "ttl_optional", "cas", "versioned"},
+    }
+
+
+def build_memkv(*, mapping=None, spec=None, dsn=None, **_) -> tuple[object, object]:
+    mapping = dict(mapping or {})
+    async_ = bool(getattr(spec, "async_", False))
+
+    namespace = str(mapping.get("namespace", "default"))
+    default_ttl_s = float(mapping.get("default_ttl_s", 0.0)) or None
+    max_items = int(mapping.get("max_items", 1_000_000))
+
+    engine = KVStore(namespace=namespace, default_ttl_s=default_ttl_s, max_items=max_items)
+
+    if async_:
+        def sessionmaker():
+            return AsyncKVSession(engine)
+    else:
+        def sessionmaker():
+            return KVSession(engine)
+
+    return engine, sessionmaker

tigrbl_engine_memkv/session.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .kv import KVStore
+
+
+class KVSession:
+    def __init__(self, engine: KVStore) -> None:
+        self._engine = engine
+        self._closed = False
+
+    def close(self) -> None:
+        self._closed = True
+
+    def get(self, key: str, default: Any = None) -> Any:
+        self._require_open()
+        return self._engine.get(key, default)
+
+    def get_version(self, key: str) -> int | None:
+        self._require_open()
+        return self._engine.get_version(key)
+
+    def set(self, key: str, value: Any, *, ttl_s: float | None = None) -> int:
+        self._require_open()
+        return self._engine.set(key, value, ttl_s=ttl_s)
+
+    def cas(self, key: str, expected_version: int, value: Any, *, ttl_s: float | None = None) -> int | None:
+        self._require_open()
+        return self._engine.cas(key, expected_version, value, ttl_s=ttl_s)
+
+    def delete(self, key: str) -> bool:
+        self._require_open()
+        return self._engine.delete(key)
+
+    def keys(self, prefix: str = "") -> list[str]:
+        self._require_open()
+        return self._engine.keys(prefix)
+
+    def reset(self) -> None:
+        self._require_open()
+        self._engine.reset()
+
+    def stats(self) -> dict:
+        self._require_open()
+        return self._engine.stats()
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("session is closed")
+
+
+class AsyncKVSession(KVSession):
+    async def close(self) -> None:  # type: ignore[override]
+        super().close()

tigrbl_engine_memkv-0.1.10.dev1.dist-info/METADATA

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

tigrbl_engine_memkv-0.1.10.dev1.dist-info/RECORD

@@ -0,0 +1,8 @@
+tigrbl_engine_memkv/__init__.py,sha256=tXbRXsO0NE_UV1kIHiZTTQQH0fj0U2KoxxNusu_gzrM,48
+tigrbl_engine_memkv/kv.py,sha256=ZjkdH5x7ZribYG6aIuVAmI1joWEFmf6DZBzcaVCsIwc,5083
+tigrbl_engine_memkv/plugin.py,sha256=4foQtxcFwsmKvFVTmDJITIS8rAc7w4Dd4akcbgYFjjk,1143
+tigrbl_engine_memkv/session.py,sha256=4ztuZyHI2AA6CL3lKkCfvNOm8wc_qG6u7VDE87HK-Oc,1558
+tigrbl_engine_memkv-0.1.10.dev1.dist-info/METADATA,sha256=xNKU14mI-1ji0izqt9dIh8Y3Jo1ipp5xUZhyq0beni0,121
+tigrbl_engine_memkv-0.1.10.dev1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tigrbl_engine_memkv-0.1.10.dev1.dist-info/entry_points.txt,sha256=gW5z9mC1ZuKPBD9OP0NNjf6tGz6tfO1YgRrRlykS1Ec,60
+tigrbl_engine_memkv-0.1.10.dev1.dist-info/RECORD,,

tigrbl_engine_memkv-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_memkv-0.1.10.dev1.dist-info/entry_points.txt

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