quadkit-cache 0.0.44__tar.gz → 0.0.45__tar.gz

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit-cache
-Version: 0.0.44
+Version: 0.0.45
 Summary: Multi-backend caching system for Quadkit Framework - Redis, Memcached, and in-memory caching
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit-cache"
-version = "0.0.44"
+version = "0.0.45"
 description = "Multi-backend caching system for Quadkit Framework - Redis, Memcached, and in-memory caching"
 readme = "README.md"
 requires-python = ">=3.11"

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/src/quadkit/cache/backends/memory/backend.py

@@ -54,7 +54,8 @@ class MemoryCacheBackend(CacheBackendProtocol):
             hooks: Optional hook registry for lifecycle emission.
         """
         self.config = config or default_cache_config()
-        self._store = MemoryStateStore(max_size=max_size)  # type: ignore[abstract]
+        self.max_size = max_size
+        self._store = MemoryStateStore(max_size=max_size)
         self._metrics = CacheMetrics()
         self._evictions = 0
         self._hooks = hooks
@@ -317,17 +318,29 @@ class MemoryCacheBackend(CacheBackendProtocol):
             Dict with ``hits``, ``misses``, ``evictions``, and ``entries``
             counts, or None when statistics are unavailable.
         """
+        store_stats = getattr(self._store, "get_stats", None)
+        store_evictions = 0
+        store_entries = len(self._store._data)
+        if callable(store_stats):
+            reported = store_stats() or {}
+            store_evictions = int(reported.get("evictions", 0) or 0)
+            store_entries = int(reported.get("entries", store_entries) or 0)
         return {
             "hits": self._metrics.hits,
             "misses": self._metrics.misses,
-            "evictions": self._evictions,
-            "entries": len(self._store._data),
+            # Both the backend's own eviction paths (tag/LRU maintenance) and
+            # the store's capacity evictions.
+            "evictions": self._evictions + store_evictions,
+            "entries": store_entries,
         }
 
     def reset_stats(self) -> None:
         """Reset counters without evicting cached entries."""
         self._metrics.reset()
         self._evictions = 0
+        store = self._store
+        if hasattr(store, "eviction_count"):
+            store.eviction_count = 0
 
     async def health_check(self, timeout: float = 5.0) -> HealthCheckResult:
         """

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/src/quadkit/cache/backends/memory/kv.py

@@ -43,7 +43,7 @@ class InMemoryStorage(StorageBackendProtocol):
     def _get_store(self, namespace: str) -> MemoryStateStore:
         """Return (or create) the MemoryStateStore for *namespace*."""
         if namespace not in self._stores:
-            self._stores[namespace] = MemoryStateStore(  # type: ignore[abstract]
+            self._stores[namespace] = MemoryStateStore(
                 max_size=self.max_size,
             )
         return self._stores[namespace]

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/src/quadkit/cache/backends/memory_state.py

@@ -31,6 +31,10 @@ class MemoryStateStore(StateStoreProtocol):
                 entry is evicted first.  ``None`` (default) disables eviction.
         """
         self.max_size = max_size
+        #: Entries dropped to make room for new ones. Expired entries that
+        #: happen to be reaped during a write are not evictions — they were
+        #: going to disappear anyway — so only the LRU drop is counted here.
+        self.eviction_count = 0
         # OrderedDict preserves insertion/access order for LRU tracking.
         self._data: OrderedDict[str, dict[str, Any]] = OrderedDict()
 
@@ -98,6 +102,7 @@ class MemoryStateStore(StateStoreProtocol):
                 self._evict_expired()
                 if len(self._data) >= self.max_size:
                     self._data.popitem(last=False)  # remove least-recently used
+                    self.eviction_count += 1
 
             self._data[key] = {"value": serialized_value, "expires_at": expires_at}
 
@@ -120,6 +125,44 @@ class MemoryStateStore(StateStoreProtocol):
             return False
         return True
 
+    async def expire(self, key: str, ttl: int) -> bool:
+        """Set a new expiration on an existing, non-expired key."""
+        entry = self._data.get(key)
+        if entry is None:
+            return False
+        now = ambient_clock.timestamp()
+        expires_at = entry.get("expires_at")
+        if expires_at is not None and now > expires_at:
+            del self._data[key]
+            return False
+        entry["expires_at"] = now + ttl
+        if self.max_size is not None:
+            self._data.move_to_end(key)
+        return True
+
+    async def ttl(self, key: str) -> int:
+        """Remaining TTL in seconds; -1 with no expiry, -2 when absent."""
+        entry = self._data.get(key)
+        if entry is None:
+            return -2
+        now = ambient_clock.timestamp()
+        expires_at = entry.get("expires_at")
+        if expires_at is None:
+            return -1
+        if now > expires_at:
+            del self._data[key]
+            return -2
+        return max(0, int(expires_at - now))
+
+    async def get_many(self, keys: list[str]) -> dict[str, Any]:
+        """Fetch several keys at once; absent keys are omitted."""
+        return await self.get_bulk(keys)
+
+    async def set_many(self, items: dict[str, Any], ttl: int | None = None) -> None:
+        """Persist several key-value pairs in one call."""
+        for key, value in items.items():
+            await self.set(key, value, ttl)
+
     async def clear(self) -> None:
         """Clear all values from the store."""
         self._data.clear()
@@ -133,6 +176,19 @@ class MemoryStateStore(StateStoreProtocol):
                 result[key] = value
         return result
 
+    def get_stats(self) -> dict[str, Any]:
+        """Return occupancy and eviction counts for administrative reporting.
+
+        Reporting lives here rather than in each backend so a backend without
+        an eviction counter of its own (the memory cache) still reports the
+        evictions its store performed.
+        """
+        return {
+            "entries": len(self._data),
+            "max_size": self.max_size,
+            "evictions": self.eviction_count,
+        }
+
     async def health_check(self, timeout: float = 5.0) -> HealthCheckResult:
         """Check the health of the state store."""
         return HealthCheckResult(
@@ -142,5 +198,6 @@ class MemoryStateStore(StateStoreProtocol):
                 "driver": "memory",
                 "keys_count": len(self._data),
                 "max_size": self.max_size,
+                "evictions": self.eviction_count,
             },
         )

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/src/quadkit/cache/cli/templates/cache_repository.py.jinja2

@@ -1,4 +1,8 @@
-"""{{ entity_name }} repository with caching.
+"""Convention followed: **Repository pattern** — a cache-aside
+decorator: reads check the cache first, writes invalidate; the
+wrapped repository stays the source of truth.
+
+{{ entity_name }} repository with caching.
 
 This module provides a cached repository that wraps an underlying data
 repository and applies the cache-aside pattern:

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/src/quadkit/cache/di/_registration.py

@@ -136,7 +136,7 @@ class _CacheRegistrationMixin:
                     and resolve_backend_type(backend_config) == BackendType.REDIS
                     and backend_config.redis_url
                 ):
-                    store = RedisStateStore(  # type: ignore[abstract]
+                    store = RedisStateStore(
                         url=backend_config.redis_url,
                         prefix=backend_config.key_prefix,
                     )

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/src/quadkit/cache/service/core.py

@@ -84,7 +84,14 @@ class CacheService(PipelineMixin, InvalidationMixin, PatternsMixin):
         """
         self.provider = provider
         self._backend = backend
-        self.config = config or default_cache_config()
+        # A directly-supplied backend carries the configuration that governs
+        # key prefixing and default TTL. Adopting it when the caller passed no
+        # service config keeps the two in step: the alternative is a service
+        # reporting no prefix while every key it writes is prefixed by the
+        # backend it delegates to.
+        self.config = (
+            config or getattr(backend, "config", None) or default_cache_config()
+        )
         self._protection = protection
         self._ctx = ctx
 
@@ -433,6 +440,48 @@ class CacheService(PipelineMixin, InvalidationMixin, PatternsMixin):
         """
         return self._metrics.copy()
 
+    @property
+    def backend(self) -> CacheBackendProtocol | None:
+        """Return the backing store, or ``None`` when only a provider is set.
+
+        Admin surfaces report per-cache occupancy and eviction from the
+        backend itself; exposing it keeps that reporting out of the private
+        attribute layout.
+        """
+        return self._backend
+
+    @property
+    def key_prefix(self) -> str:
+        """Return this service's key prefix (``""`` when it has none)."""
+        return str(getattr(self.config, "key_prefix", "") or "")
+
+    @property
+    def default_ttl(self) -> int | None:
+        """Return the default TTL in seconds applied when ``set`` omits one."""
+        value = getattr(self.config, "default_ttl", None)
+        return int(value) if value is not None else None
+
+    def get_backend_stats(self) -> dict[str, int]:
+        """Return the backend's own counters for administrative reporting.
+
+        ``get_stats`` is optional on the backend protocol — a Redis backend
+        answers through ``INFO`` instead — so an unreporting backend yields
+        zeros rather than fabricated activity.
+
+        Returns:
+            Mapping with ``hits``, ``misses``, ``evictions`` and ``entries``.
+        """
+        empty = {"hits": 0, "misses": 0, "evictions": 0, "entries": 0}
+        get_stats = getattr(self._backend, "get_stats", None)
+        if not callable(get_stats):
+            return empty
+        try:
+            raw = get_stats() or {}
+        except Exception:  # noqa: BLE001 — reporting never raises
+            logger.warning("cache.backend_stats_unavailable", exc_info=True)
+            return empty
+        return {key: int(raw.get(key, 0) or 0) for key in empty}
+
     def reset_metrics(self) -> None:
         """Reset performance metrics."""
         self._metrics = {"hits": 0, "misses": 0, "errors": 0, "operations": 0}

{quadkit_cache-0.0.44 → quadkit_cache-0.0.45}/src/quadkit/cache/stores/redis_state.py

@@ -151,6 +151,32 @@ class RedisStateStore(RedisDriver, StateStoreProtocol):
         await cast("Awaitable[Any]", client.delete(self._key(key)))
         return True
 
+    async def exists(self, key: str) -> bool:
+        """Check whether a key exists."""
+        client = await self._get_client()
+        return bool(await client.exists(self._key(key)))
+
+    async def expire(self, key: str, ttl: int) -> bool:
+        """Set expiration on a key; False when the key does not exist."""
+        client = await self._get_client()
+        return bool(await cast("Awaitable[Any]", client.expire(self._key(key), ttl)))
+
+    async def ttl(self, key: str) -> int:
+        """Remaining TTL in seconds; -1 with no expiry, -2 when absent."""
+        client = await self._get_client()
+        # Redis already returns -1 for "no expiry" and -2 for "no such key",
+        # which is exactly the StateStoreProtocol contract.
+        return int(await client.ttl(self._key(key)))
+
+    async def get_many(self, keys: list[str]) -> dict[str, Any]:
+        """Fetch several keys at once; absent keys are omitted."""
+        return await self.get_bulk(keys)
+
+    async def set_many(self, items: dict[str, Any], ttl: int | None = None) -> None:
+        """Persist several key-value pairs in one call."""
+        for key, value in items.items():
+            await self.set(key, value, ttl)
+
     async def get_bulk(self, keys: list[str]) -> dict[str, Any]:
         """Get multiple values by keys"""
         client = await self._get_client()

quadkit_cache-0.0.45/tests/unit/service/test_reporting_surface.py

@@ -0,0 +1,136 @@
+"""The reporting surface admin dashboards read from a cache service.
+
+Applications ship an admin cache dashboard; it needs the service's own
+counters, the backend's counters (hits/misses/evictions/entries), the key
+prefix and the default TTL. Asking for those through private attributes is
+what this surface exists to avoid — and the eviction count in particular used
+to be invisible: the store dropped the least-recently-used entry while the
+backend reported ``evictions: 0``, so a full cache looked idle.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from quadkit.cache.backends.memory.backend import MemoryCacheBackend
+from quadkit.cache.config.operation import CacheOperationConfig
+from quadkit.cache.service.core import CacheService
+
+
+def _service(**kwargs: object) -> CacheService:
+    config = CacheOperationConfig(default_ttl=60, key_prefix="gw:test:")
+    return CacheService(
+        backend=MemoryCacheBackend(config=config, max_size=3), **kwargs
+    )
+
+
+def test_service_exposes_backend_prefix_and_ttl() -> None:
+    """Reporting reads the configuration through public properties."""
+    service = _service()
+    assert isinstance(service.backend, MemoryCacheBackend)
+    assert service.key_prefix == "gw:test:"
+    assert service.default_ttl == 60
+
+
+def test_service_adopts_the_backend_config_when_none_is_given() -> None:
+    """A backend-injected service reports the configuration it delegates to."""
+    config = CacheOperationConfig(default_ttl=15, key_prefix="gw:x:")
+    service = CacheService(backend=MemoryCacheBackend(config=config))
+    assert service.key_prefix == "gw:x:"
+    assert service.default_ttl == 15
+
+
+def test_explicit_service_config_wins() -> None:
+    """A caller-supplied service config is not overwritten by the backend's."""
+    config = CacheOperationConfig(default_ttl=15, key_prefix="gw:x:")
+    service = CacheService(
+        config=CacheOperationConfig(default_ttl=5, key_prefix="gw:y:"),
+        backend=MemoryCacheBackend(config=config),
+    )
+    assert service.key_prefix == "gw:y:"
+    assert service.default_ttl == 5
+
+
+def test_backend_stats_are_counted_from_real_operations() -> None:
+    """Hits, misses and entries come from the operations that happened."""
+    service = _service()
+
+    async def _exercise() -> None:
+        await service.set("hit", "value")
+        assert await service.get("hit") == "value"
+        assert await service.get("absent") is None
+
+    asyncio_run(_exercise())
+    stats = service.get_backend_stats()
+    assert stats == {"hits": 1, "misses": 1, "evictions": 0, "entries": 1}
+
+
+def test_backend_stats_reports_store_evictions() -> None:
+    """Filling past capacity is visible to the dashboard as evictions."""
+    service = _service()
+
+    async def _fill() -> None:
+        for index in range(6):
+            await service.set(f"key-{index}", index)
+
+    asyncio_run(_fill())
+    stats = service.get_backend_stats()
+    assert stats["entries"] == 3
+    assert stats["evictions"] == 3
+
+
+def test_backend_stats_are_zeroed_when_the_backend_cannot_report() -> None:
+    """A backend without counters yields zeros, never fabricated activity."""
+
+    class _Opaque:
+        async def get(self, key: str) -> None:
+            return None
+
+    service = CacheService(backend=_Opaque())
+    assert service.get_backend_stats() == {
+        "hits": 0,
+        "misses": 0,
+        "evictions": 0,
+        "entries": 0,
+    }
+
+
+def test_backend_stats_never_raise() -> None:
+    """A backend whose stats blow up reports zeros instead of failing a page."""
+
+    class _Exploding(MemoryCacheBackend):
+        def get_stats(self):
+            raise RuntimeError("stats unavailable")
+
+    service = CacheService(backend=_Exploding(max_size=1))
+    assert service.get_backend_stats()["entries"] == 0
+
+
+def test_reset_stats_clears_evictions_too() -> None:
+    """Resetting counters clears the store's eviction count as well."""
+    service = _service()
+
+    async def _fill() -> None:
+        for index in range(6):
+            await service.set(f"key-{index}", index)
+
+    asyncio_run(_fill())
+    assert service.get_backend_stats()["evictions"] == 3
+
+    service.backend.reset_stats()  # type: ignore[union-attr]
+    assert service.get_backend_stats()["evictions"] == 0
+
+
+def asyncio_run(coro) -> None:
+    """Run a coroutine to completion without pytest-asyncio ceremony."""
+    import asyncio
+
+    asyncio.run(coro)
+
+
+@pytest.mark.parametrize("key_prefix", ["", "gw:user:"])
+def test_prefix_round_trips_through_the_service(key_prefix: str) -> None:
+    """The reported prefix is the one keys are actually built with."""
+    config = CacheOperationConfig(key_prefix=key_prefix)
+    service = CacheService(backend=MemoryCacheBackend(config=config))
+    assert service.key_prefix == key_prefix

quadkit_cache-0.0.45/tests/unit/test_state_store_protocol_conformance.py

@@ -0,0 +1,196 @@
+"""Guards for the ``StateStoreProtocol`` implementations.
+
+``StateStoreProtocol`` is a plain ``typing.Protocol`` whose members carry
+docstring-only bodies. Subclassing it therefore does **not** make Python enforce
+anything at runtime: an implementation that forgets a method silently inherits
+the stub, and calling that method returns ``None`` instead of raising. Only
+mypy notices.
+
+That is exactly what happened — ``MemoryStateStore`` shipped without
+``expire``/``ttl``/``get_many``/``set_many`` and ``RedisStateStore`` without
+``exists`` on top of those four, so three call sites carried
+``# type: ignore[abstract]`` to silence the resulting
+"cannot instantiate abstract class" errors.
+
+The first test is the regression guard: it fails if any implementation starts
+inheriting a protocol stub again. The rest pin the behaviour the protocol's
+docstrings promise.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+import pytest
+
+from quadkit.cache.backends.memory_state import MemoryStateStore
+from quadkit.cache.stores.redis_state import RedisStateStore
+from quadkit.contracts.infra.state import StateStoreProtocol
+
+
+def _protocol_methods() -> list[str]:
+    """Names declared directly on the protocol (not inherited dunders)."""
+    return sorted(
+        name
+        for name, member in vars(StateStoreProtocol).items()
+        if not name.startswith("_") and inspect.isfunction(member)
+    )
+
+
+def _inherited_stub(cls: type, method: str) -> bool:
+    """True when *cls* resolves *method* to the protocol's own stub body."""
+    fn = getattr(cls, method, None)
+    if fn is None:
+        return True
+    return getattr(fn, "__qualname__", "").startswith("StateStoreProtocol")
+
+
+class _FakeClient:
+    """Minimal async stand-in for ``redis.asyncio.Redis``."""
+
+    def __init__(self) -> None:
+        self.exists_result: Any = 1
+        self.expire_result: Any = True
+        self.ttl_result: Any = 42
+        self.mget_result: Any = []
+        self.set_calls: list[tuple] = []
+        self.expire_calls: list[tuple] = []
+
+    async def exists(self, key: str) -> Any:
+        return self.exists_result
+
+    async def expire(self, key: str, seconds: int) -> Any:
+        self.expire_calls.append((key, seconds))
+        return self.expire_result
+
+    async def ttl(self, key: str) -> Any:
+        return self.ttl_result
+
+    async def mget(self, keys: list[str]) -> Any:
+        return self.mget_result
+
+    async def set(self, key: str, value: str, ex: int | None = None) -> Any:
+        self.set_calls.append((key, value, ex))
+        return True
+
+
+@pytest.mark.parametrize("cls", [MemoryStateStore, RedisStateStore])
+def test_every_protocol_method_is_really_implemented(cls: type) -> None:
+    """No implementation may resolve a method to the protocol's empty stub."""
+    methods = _protocol_methods()
+    assert methods, "StateStoreProtocol declared nothing — the guard is vacuous"
+    inherited = [m for m in methods if _inherited_stub(cls, m)]
+    assert inherited == [], f"{cls.__name__} inherits protocol stubs for {inherited}"
+
+
+class TestMemoryStateStoreContract:
+    @pytest.mark.asyncio
+    async def test_ttl_reports_no_expiry(self) -> None:
+        store = MemoryStateStore()
+        await store.set("k", "v")
+        assert await store.ttl("k") == -1
+
+    @pytest.mark.asyncio
+    async def test_ttl_reports_absent_key(self) -> None:
+        store = MemoryStateStore()
+        assert await store.ttl("nope") == -2
+
+    @pytest.mark.asyncio
+    async def test_ttl_reports_remaining_seconds(self) -> None:
+        store = MemoryStateStore()
+        await store.set("k", "v", ttl=60)
+        remaining = await store.ttl("k")
+        assert 0 < remaining <= 60
+
+    @pytest.mark.asyncio
+    async def test_expire_sets_a_new_deadline(self) -> None:
+        store = MemoryStateStore()
+        await store.set("k", "v")
+        assert await store.expire("k", 30) is True
+        remaining = await store.ttl("k")
+        assert 0 < remaining <= 30
+
+    @pytest.mark.asyncio
+    async def test_expire_on_missing_key_returns_false(self) -> None:
+        store = MemoryStateStore()
+        assert await store.expire("nope", 30) is False
+
+    @pytest.mark.asyncio
+    async def test_expire_on_expired_key_returns_false_and_reaps(self) -> None:
+        store = MemoryStateStore()
+        await store.set("k", "v", ttl=-1)  # already in the past
+        assert await store.expire("k", 30) is False
+        assert await store.get("k") is None
+
+    @pytest.mark.asyncio
+    async def test_get_many_omits_absent_keys(self) -> None:
+        store = MemoryStateStore()
+        await store.set("a", 1)
+        await store.set("b", {"nested": True})
+        assert await store.get_many(["a", "b", "missing"]) == {
+            "a": 1,
+            "b": {"nested": True},
+        }
+
+    @pytest.mark.asyncio
+    async def test_set_many_applies_ttl_to_every_entry(self) -> None:
+        store = MemoryStateStore()
+        await store.set_many({"a": 1, "b": 2}, ttl=120)
+        assert await store.get_many(["a", "b"]) == {"a": 1, "b": 2}
+        for key in ("a", "b"):
+            remaining = await store.ttl(key)
+            assert 0 < remaining <= 120
+
+
+class TestRedisStateStoreContract:
+    @pytest.mark.asyncio
+    async def test_exists_maps_truthiness(self) -> None:
+        client = _FakeClient()
+        store = RedisStateStore(client=client)
+        assert await store.exists("k") is True
+        client.exists_result = 0
+        assert await store.exists("k") is False
+
+    @pytest.mark.asyncio
+    async def test_expire_forwards_key_and_seconds(self) -> None:
+        client = _FakeClient()
+        store = RedisStateStore(prefix="p:", client=client)
+        assert await store.expire("k", 90) is True
+        assert client.expire_calls == [("p:k", 90)]
+
+    @pytest.mark.asyncio
+    async def test_expire_returns_false_when_key_missing(self) -> None:
+        client = _FakeClient()
+        client.expire_result = False
+        store = RedisStateStore(client=client)
+        assert await store.expire("k", 90) is False
+
+    @pytest.mark.asyncio
+    async def test_ttl_passes_through_redis_sentinels(self) -> None:
+        client = _FakeClient()
+        store = RedisStateStore(client=client)
+        assert await store.ttl("k") == 42
+        client.ttl_result = -1
+        assert await store.ttl("k") == -1
+        client.ttl_result = -2
+        assert await store.ttl("k") == -2
+
+    @pytest.mark.asyncio
+    async def test_get_many_returns_found_keys_only(self) -> None:
+        client = _FakeClient()
+        client.mget_result = ['{"a":1}', None]
+        store = RedisStateStore(client=client)
+        assert await store.get_many(["a", "b"]) == {"a": {"a": 1}}
+
+    @pytest.mark.asyncio
+    async def test_set_many_writes_each_entry_with_ttl(self) -> None:
+        client = _FakeClient()
+        store = RedisStateStore(client=client)
+        await store.set_many({"a": 1, "b": {"n": 2}}, ttl=15)
+        # Each entry is serialised on its own: `set_many` forwards the value,
+        # not a wrapper dict.
+        assert list(client.set_calls) == [
+            ("a", b"1", 15),
+            ("b", b'{"n":2}', 15),
+        ]