loom-kernel 2.4.0__tar.gz → 2.5.0__tar.gz

{loom_kernel-2.4.0 → loom_kernel-2.5.0}/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 ### core
 
+- **core:** a memory cache alias can be bounded. `cache: max_size` (entries) and
+  the new `cache: max_bytes` (stored payload bytes) serve every
+  `aiocache.SimpleMemoryCache` alias through `loom.core.cache.memory.BoundedMemoryCache`,
+  which evicts least-recently-used entries past either bound. Before, `max_size`
+  failed at boot (aiocache's class does not accept it) and a memory alias grew
+  without limit. Redis and the other server backends are unaffected.
+
 - **core:** `loom.core.model` (module `_loom_type`) is the one module that decides whether
   a boundary type is a `msgspec.Struct` or a strict `pydantic.BaseModel`.
   `loom_type(symbol)` resolves an authored symbol by `issubclass`,

{loom_kernel-2.4.0 → loom_kernel-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.4.0
+Version: 2.5.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-2.4.0 → loom_kernel-2.5.0}/docs/rest/cache.md

@@ -59,7 +59,8 @@ cache:
   ttl:                      # per-entity overrides; append _list for the list side
     user: 600
     user_list: 300
-  max_size: 1000            # injected into every aiocache.SimpleMemoryCache alias
+  max_size: 1000            # entry cap for every aiocache.SimpleMemoryCache alias
+  max_bytes: 33554432       # byte cap for the same aliases; either or both
   aiocache_alias: data      # alias that stores entities (default: "default")
   counter_alias: counters   # alias that stores the generation counters (default: same as aiocache_alias)
   aiocache_config:
@@ -80,6 +81,7 @@ cache:
 | `ttl_jitter` | `0.1` | Random spread applied per write so a burst does not expire at once; `0` disables it |
 | `ttl` | `{}` | Per-entity overrides; `user` for the entity read, `user_list` for the list side |
 | `max_size` | none | Entry cap for `aiocache.SimpleMemoryCache` aliases; ignored by Redis |
+| `max_bytes` | none | Byte cap on the stored payloads of the same aliases; ignored by Redis |
 | `aiocache_alias` | `default` | Alias of the data backend |
 | `counter_alias` | none | Alias of the counter backend; falls back to `aiocache_alias` |
 | `aiocache_config` | `{}` | Alias map handed to `aiocache`, one entry per alias |
@@ -94,6 +96,16 @@ Redis `INCR`), and a serializer in front of them would break that. When
 falls back to a non-atomic get-and-set, which is fine for a single process and
 not for several.
 
+`aiocache.SimpleMemoryCache` itself accepts no bound: it only shrinks by TTL.
+An alias configured with that class and a bound — `max_size` or `max_bytes` at
+the `cache:` level, or its own inside `aiocache_config`, which win — is served by
+`loom.core.cache.memory.BoundedMemoryCache` instead, which evicts the least
+recently used entries the moment a write crosses either bound. Bytes are
+measured on the stored payload, so on the data alias they are the serialized
+size, exactly. A single value larger than `max_bytes` is kept and evicts
+everything else, because a `get` right after a `set` must not miss. Redis and
+every other server backend are forwarded unchanged and bound their own memory.
+
 The YAML reads `aiocache_config:` only. `CacheConfig.from_mapping` also accepts
 the short key `aiocache:` for callers building the config by hand; from the
 YAML that key — like any other key `CacheConfig` does not declare, `ttls:` for
@@ -410,7 +422,7 @@ cache:
 
 Keep a separate counter alias for any multi-process deployment: with one alias
 the counters share the data serializer and lose the atomic increment.
-`max_size` has no effect on Redis.
+`max_size` and `max_bytes` have no effect on Redis.
 
 ## Failures
 

{loom_kernel-2.4.0 → loom_kernel-2.5.0}/src/loom/core/cache/__init__.py

@@ -9,11 +9,13 @@ from loom.core.cache.decorators import cache_call, cache_query, cached
 from loom.core.cache.dependency import GenerationalDependencyResolver
 from loom.core.cache.errors import CacheWriteError
 from loom.core.cache.gateway import CacheGateway
+from loom.core.cache.memory import BoundedMemoryCache
 from loom.core.cache.repository import CachedRepository
 from loom.core.cache.serializer import MsgspecSerializer
 
 __all__ = [
     "BatchFingerprintResolver",
+    "BoundedMemoryCache",
     "CacheGateway",
     "CachedCalls",
     "CacheBackend",

{loom_kernel-2.4.0 → loom_kernel-2.5.0}/src/loom/core/cache/abc/config.py

@@ -41,8 +41,12 @@ class CacheConfig(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fi
         ttl: Per-entity TTL overrides keyed by entity name.  Append ``_list``
             for list overrides (e.g. ``{"user": 300, "user_list": 150}``).
         max_size: Maximum number of entries for ``aiocache.SimpleMemoryCache``
-            backends.  Injected automatically when calling
-            :meth:`~loom.core.cache.CacheGateway.apply_config`.
+            backends.  :meth:`~loom.core.cache.CacheGateway.apply_config` turns
+            such an alias into a :class:`~loom.core.cache.memory.BoundedMemoryCache`
+            that evicts least-recently-used entries past the bound.
+            Has no effect on Redis or other non-memory backends.
+        max_bytes: Maximum bytes the stored payloads of a memory alias may
+            occupy, applied the same way as ``max_size``; both may be set.
             Has no effect on Redis or other non-memory backends.
 
     Example YAML (Redis + separate counter backend)::
@@ -97,11 +101,15 @@ class CacheConfig(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fi
     ttl_jitter: float = 0.1
     ttl: dict[str, int] = msgspec.field(default_factory=dict)
     max_size: int | None = None
+    max_bytes: int | None = None
 
     def __post_init__(self) -> None:
         if not 0.0 <= self.ttl_jitter < 1.0:
             msg = f"ttl_jitter must be in [0, 1), got {self.ttl_jitter}"
             raise ValueError(msg)
+        for name, bound in (("max_size", self.max_size), ("max_bytes", self.max_bytes)):
+            if bound is not None and bound < 1:
+                raise ValueError(f"{name} must be at least 1, got {bound}")
 
     @property
     def effective_counter_alias(self) -> str:
@@ -120,6 +128,7 @@ class CacheConfig(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fi
         """
         raw_counter_alias = data.get("counter_alias")
         raw_max_size = data.get("max_size")
+        raw_max_bytes = data.get("max_bytes")
         return cls(
             enabled=bool(data.get("enabled", True)),
             aiocache_alias=str(data.get("aiocache_alias", "default")),
@@ -130,6 +139,7 @@ class CacheConfig(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fi
             ttl_jitter=float(data.get("ttl_jitter", 0.1)),
             ttl={str(k): int(v) for k, v in dict(data.get("ttl", {})).items()},
             max_size=int(raw_max_size) if raw_max_size is not None else None,
+            max_bytes=int(raw_max_bytes) if raw_max_bytes is not None else None,
         )
 
     def ttl_for_single(self, entity: str) -> int:

{loom_kernel-2.4.0 → loom_kernel-2.5.0}/src/loom/core/cache/gateway.py

@@ -17,6 +17,7 @@ if TYPE_CHECKING:
 T = TypeVar("T")
 
 _SIMPLE_MEMORY_CACHE = "SimpleMemoryCache"
+_BOUNDED_MEMORY_CACHE = "loom.core.cache.memory.BoundedMemoryCache"
 _DEFAULT_ALIAS = "default"
 _MEMORY_FALLBACK = {"cache": "aiocache.SimpleMemoryCache"}
 
@@ -97,10 +98,11 @@ class CacheGateway:
     def apply_config(cls, config: CacheConfig) -> None:
         """Configure aiocache from a :class:`~loom.core.cache.abc.config.CacheConfig`.
 
-        Equivalent to :meth:`configure` but also injects ``config.max_size``
-        into every ``aiocache.SimpleMemoryCache`` backend entry that does not
-        already declare its own ``max_size``.  Entries for other backend types
-        (Redis, Memcached, …) are forwarded unchanged.
+        Equivalent to :meth:`configure`, except that an ``aiocache.SimpleMemoryCache``
+        entry with a bound — ``config.max_size``, ``config.max_bytes``, or its own
+        ``max_size``/``max_bytes``, which win — becomes a
+        :class:`~loom.core.cache.memory.BoundedMemoryCache`.  Entries for other
+        backend types (Redis, Memcached, …) are forwarded unchanged.
 
         Args:
             config: Resolved cache configuration.
@@ -129,8 +131,18 @@ class CacheGateway:
                 raw[alias] = backend_cfg
                 continue
             entry = dict(backend_cfg)
-            if config.max_size is not None and _SIMPLE_MEMORY_CACHE in str(entry.get("cache", "")):
-                entry.setdefault("max_size", config.max_size)
+            bounded = (
+                config.max_size is not None
+                or config.max_bytes is not None
+                or "max_size" in entry
+                or "max_bytes" in entry
+            )
+            if bounded and _SIMPLE_MEMORY_CACHE in str(entry.get("cache", "")):
+                entry["cache"] = _BOUNDED_MEMORY_CACHE
+                if config.max_size is not None:
+                    entry.setdefault("max_size", config.max_size)
+                if config.max_bytes is not None:
+                    entry.setdefault("max_bytes", config.max_bytes)
             raw[alias] = entry
         if _DEFAULT_ALIAS not in raw:
             raw[_DEFAULT_ALIAS] = dict(raw.get(config.aiocache_alias) or _MEMORY_FALLBACK)

loom_kernel-2.5.0/src/loom/core/cache/memory.py

@@ -0,0 +1,174 @@
+"""An in-memory aiocache backend that evicts when it gets too big.
+
+``aiocache.SimpleMemoryCache`` accepts no bound: passing it ``max_size`` fails at
+construction, and without one it only shrinks by TTL. This backend is that class
+plus a ledger, with the same contract, a limit on entries and/or bytes, and
+least-recently-used eviction the moment a write crosses either one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections import OrderedDict
+from typing import Any
+
+from aiocache import SimpleMemoryCache  # type: ignore[import-untyped]
+
+__all__ = ["BoundedMemoryCache"]
+
+
+def _cost(value: object) -> int:
+    """Bytes *value* is charged for.
+
+    ``bytes`` and ``str`` get their exact wire length because that is what a
+    serialized alias stores; anything else is a raw object on an unserialized
+    alias, where ``getsizeof``'s rough estimate is all there is.
+    """
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return len(value)
+    if isinstance(value, str):
+        return len(value.encode())
+    return sys.getsizeof(value)
+
+
+class _Ledger(OrderedDict[str, Any]):
+    """The store: an ``OrderedDict`` in recency order that also counts bytes.
+
+    ``SimpleMemoryBackend`` only ever calls ``get``, ``__setitem__``, ``pop``,
+    ``__contains__`` and ``list()`` on its store, so those keep the order and the
+    byte count right whichever path of the parent touches them. The cost is
+    recorded at write time and refunded from that record: a caller may mutate a
+    raw value it still references, so recomputing it on delete would drift.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.bytes = 0
+        self._costs: dict[str, int] = {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        if key in self:
+            self.move_to_end(key)
+            return super().__getitem__(key)
+        return default
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        cost = _cost(value)
+        self.bytes += cost - self._costs.get(key, 0)
+        self._costs[key] = cost
+        super().__setitem__(key, value)
+        self.move_to_end(key)
+
+    def __delitem__(self, key: str) -> None:
+        super().__delitem__(key)
+        self.bytes -= self._costs.pop(key)
+
+    def pop(self, key: str, default: Any = None) -> Any:
+        if key not in self:
+            return default
+        value = super().__getitem__(key)
+        del self[key]
+        return value
+
+    def popitem(self, last: bool = True) -> tuple[str, Any]:
+        key, value = super().popitem(last)
+        self.bytes -= self._costs.pop(key)
+        return key, value
+
+    def clear(self) -> None:
+        super().clear()
+        self._costs.clear()
+        self.bytes = 0
+
+
+# aiocache ships no stubs, so its class is ``Any`` to mypy.
+class BoundedMemoryCache(SimpleMemoryCache):  # type: ignore[misc]
+    """``SimpleMemoryCache`` with a ceiling on entries and bytes, evicting LRU.
+
+    Args:
+        max_size: Most entries kept at once, or ``None`` for no such bound.
+        max_bytes: Most bytes kept at once, measured on the stored payload, or
+            ``None`` for no such bound.
+        **kwargs: Everything ``SimpleMemoryCache`` accepts.
+
+    A single value larger than ``max_bytes`` is stored and evicts everything
+    else: refusing it would make ``get`` after ``set`` miss, which the contract
+    does not allow. A ``set`` whose ``_cas_token`` does not match stores nothing
+    but still counts as a use of the key.
+    """
+
+    NAME = "bounded_memory"
+
+    def __init__(
+        self,
+        *,
+        max_size: int | None = None,
+        max_bytes: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        for name, bound in (("max_size", max_size), ("max_bytes", max_bytes)):
+            if bound is not None and bound < 1:
+                raise ValueError(f"{name} must be at least 1, got {bound}")
+        super().__init__(**kwargs)
+        self.max_size = max_size
+        self.max_bytes = max_bytes
+        self.evictions = 0
+        # The parent declares ``_cache`` as a plain dict; the ledger is kept under
+        # its own name so its extra attributes stay typed, and handed to the
+        # parent's slot for every path the parent runs.
+        self._ledger = _Ledger()
+        self._cache = self._ledger
+        self._handlers: dict[str, asyncio.TimerHandle] = {}
+
+    @property
+    def bytes(self) -> int:
+        """Bytes the stored payloads occupy right now."""
+        return self._ledger.bytes
+
+    async def _set(
+        self,
+        key: str,
+        value: Any,
+        ttl: Any = None,
+        _cas_token: Any = None,
+        _conn: Any = None,
+    ) -> Any:
+        stored = await super()._set(key, value, ttl=ttl, _cas_token=_cas_token, _conn=_conn)
+        if stored:
+            self._evict()
+        return stored
+
+    async def _increment(self, key: str, delta: int, _conn: Any = None) -> Any:
+        result = await super()._increment(key, delta, _conn=_conn)
+        self._evict()
+        return result
+
+    async def _clear(self, namespace: Any = None, _conn: Any = None) -> Any:
+        # The parent's no-namespace path replaces self._cache with a plain dict,
+        # which would drop the ledger for good; it is emptied here instead.
+        if namespace:
+            return await super()._clear(namespace, _conn=_conn)
+        self._ledger.clear()
+        for handle in self._handlers.values():
+            handle.cancel()
+        self._handlers.clear()
+        return True
+
+    def _evict(self) -> None:
+        """Drop least recently used entries until both bounds hold.
+
+        The entry just written is the most recent, so the ``> 1`` guard is what
+        keeps it when it alone is over the byte bound.
+        """
+        while len(self._ledger) > 1 and self._over():
+            key, _ = self._ledger.popitem(last=False)
+            handle = self._handlers.pop(key, None)
+            if handle:
+                handle.cancel()
+            self.evictions += 1
+
+    def _over(self) -> bool:
+        if self.max_size is not None and len(self._ledger) > self.max_size:
+            return True
+        return self.max_bytes is not None and self._ledger.bytes > self.max_bytes

loom_kernel-2.5.0/tests/unit/core/cache/test_bounded_memory.py

@@ -0,0 +1,201 @@
+"""``BoundedMemoryCache`` and the ``apply_config`` switch that installs it."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from aiocache import caches
+
+from loom.core.cache import BoundedMemoryCache, CacheConfig, CacheGateway
+from loom.core.cache.serializer import MsgspecSerializer
+
+pytestmark = pytest.mark.asyncio
+
+
+def _payload(size: int) -> bytes:
+    return b"x" * size
+
+
+class TestByteBound:
+    async def test_the_least_recently_used_entry_goes_first(self) -> None:
+        cache = BoundedMemoryCache(max_bytes=30)
+        await cache.set("a", _payload(10))
+        await cache.set("b", _payload(10))
+        await cache.set("c", _payload(10))
+        await cache.get("a")  # a becomes the most recent; b is now the oldest
+        await cache.set("d", _payload(10))
+        assert await cache.get("b") is None
+        assert await cache.get("a") == _payload(10)
+        assert await cache.get("c") == _payload(10)
+        assert await cache.get("d") == _payload(10)
+        assert cache.bytes == 30
+        assert cache.evictions == 1
+
+    async def test_overwriting_a_key_counts_only_the_new_payload(self) -> None:
+        cache = BoundedMemoryCache(max_bytes=100)
+        await cache.set("a", _payload(40))
+        await cache.set("a", _payload(10))
+        assert cache.bytes == 10
+        assert cache.evictions == 0
+
+    async def test_a_value_over_the_whole_bound_is_kept_alone(self) -> None:
+        cache = BoundedMemoryCache(max_bytes=10)
+        await cache.set("small", _payload(5))
+        await cache.set("huge", _payload(50))
+        assert await cache.get("huge") == _payload(50)
+        assert await cache.get("small") is None
+        assert cache.bytes == 50
+
+    async def test_delete_and_clear_release_bytes(self) -> None:
+        cache = BoundedMemoryCache(max_bytes=100)
+        await cache.set("a", _payload(10))
+        await cache.set("b", _payload(10))
+        await cache.delete("a")
+        assert cache.bytes == 10
+        await cache.clear()
+        assert cache.bytes == 0
+        assert await cache.get("b") is None
+
+    async def test_a_raw_value_mutated_after_set_is_refunded_what_it_was_charged(self) -> None:
+        # Default serializer is NullSerializer: the cache keeps the caller's object.
+        cache = BoundedMemoryCache(max_bytes=10_000)
+        payload: dict[str, int] = {}
+        await cache.set("k", payload)
+        charged = cache.bytes
+        payload.update({str(index): index for index in range(100)})
+        await cache.delete("k")
+        assert (charged, cache.bytes) == (charged, 0)
+
+    async def test_multi_set_evicts_within_the_batch(self) -> None:
+        cache = BoundedMemoryCache(max_size=2)
+        await cache.multi_set([("a", 1), ("b", 2), ("c", 3)])
+        assert await cache.multi_get(["a", "b", "c"]) == [None, 2, 3]
+
+    async def test_add_is_bounded_and_still_refuses_an_existing_key(self) -> None:
+        cache = BoundedMemoryCache(max_size=1)
+        await cache.add("a", 1)
+        await cache.add("b", 2)
+        assert await cache.get("a") is None
+        with pytest.raises(ValueError, match="already exists"):
+            await cache.add("b", 3)
+
+    async def test_clear_with_a_namespace_keeps_the_ledger_and_the_rest(self) -> None:
+        cache = BoundedMemoryCache(max_bytes=100)
+        await cache.set("ns:a", _payload(10))
+        await cache.set("other", _payload(10))
+        await cache.clear(namespace="ns")
+        assert cache.bytes == 10
+        await cache.set("ns:b", _payload(10))
+        assert cache.bytes == 20
+
+    async def test_expire_then_eviction_leaves_no_timer_behind(self) -> None:
+        cache = BoundedMemoryCache(max_size=1)
+        await cache.set("a", 1)
+        await cache.expire("a", 10)
+        await cache.set("b", 2)
+        assert "a" not in cache._handlers
+
+    async def test_a_ttl_expiry_releases_bytes_and_an_eviction_cancels_the_timer(self) -> None:
+        cache = BoundedMemoryCache(max_bytes=15)
+        await cache.set("a", _payload(10), ttl=0.01)
+        await cache.set("b", _payload(10), ttl=10)  # evicts a, whose timer must go
+        assert "a" not in cache._handlers
+        await asyncio.sleep(0.03)
+        assert cache.bytes == 10
+        await cache.set("c", _payload(5), ttl=0.01)
+        await asyncio.sleep(0.03)
+        assert cache.bytes == 10
+        assert await cache.get("c") is None
+
+
+class TestEntryBound:
+    async def test_entries_past_max_size_are_evicted_lru(self) -> None:
+        cache = BoundedMemoryCache(max_size=2)
+        await cache.set("a", 1)
+        await cache.set("b", 2)
+        await cache.get("a")
+        await cache.set("c", 3)
+        assert await cache.get("b") is None
+        assert await cache.get("a") == 1
+        assert await cache.get("c") == 3
+
+    async def test_increment_is_bounded_too(self) -> None:
+        cache = BoundedMemoryCache(max_size=1)
+        await cache.increment("first")
+        await cache.increment("second")
+        assert await cache.get("first") is None
+        assert await cache.get("second") == 1
+
+    async def test_bounds_below_one_are_refused(self) -> None:
+        with pytest.raises(ValueError, match="max_size"):
+            BoundedMemoryCache(max_size=0)
+        with pytest.raises(ValueError, match="max_bytes"):
+            BoundedMemoryCache(max_bytes=-1)
+
+
+class TestApplyConfig:
+    def teardown_method(self) -> None:
+        caches._caches.clear()
+        caches._config = {"default": {"cache": "aiocache.SimpleMemoryCache"}}
+
+    async def test_a_memory_alias_with_a_bound_builds_and_evicts(self) -> None:
+        # Regression: loom 2.1.3 injected ``max_size`` into ``SimpleMemoryCache``,
+        # which does not accept it, so ``caches.get`` raised ``TypeError``.
+        config = CacheConfig(
+            aiocache_alias="data",
+            max_size=2,
+            max_bytes=1024,
+            aiocache_config={
+                "data": {
+                    "cache": "aiocache.SimpleMemoryCache",
+                    "serializer": {"class": "loom.core.cache.serializer.MsgspecSerializer"},
+                }
+            },
+        )
+        CacheGateway.apply_config(config)
+        gateway = CacheGateway(alias="data")
+        backend = gateway._cache
+        assert isinstance(backend, BoundedMemoryCache)
+        assert isinstance(backend.serializer, MsgspecSerializer)
+        assert (backend.max_size, backend.max_bytes) == (2, 1024)
+        for index in range(3):
+            await gateway.set_value(f"k{index}", {"index": index})
+        assert await gateway.get_value("k0") is None
+        assert await gateway.get_value("k2") == {"index": 2}
+
+    @pytest.mark.parametrize("global_bound", [None, 100])
+    def test_an_alias_declaring_its_own_bound_keeps_it(self, global_bound: int | None) -> None:
+        config = CacheConfig(
+            aiocache_alias="data",
+            max_size=global_bound,
+            aiocache_config={"data": {"cache": "aiocache.SimpleMemoryCache", "max_size": 5}},
+        )
+        CacheGateway.apply_config(config)
+        backend = CacheGateway(alias="data")._cache
+        assert isinstance(backend, BoundedMemoryCache)
+        assert backend.max_size == 5
+
+    def test_without_a_bound_the_plain_class_is_kept(self) -> None:
+        config = CacheConfig(
+            aiocache_alias="data",
+            aiocache_config={"data": {"cache": "aiocache.SimpleMemoryCache"}},
+        )
+        CacheGateway.apply_config(config)
+        assert type(CacheGateway(alias="data")._cache).__name__ == "SimpleMemoryCache"
+
+    def test_a_redis_alias_is_forwarded_unchanged(self) -> None:
+        redis = {"cache": "aiocache.RedisCache", "endpoint": "redis", "port": 6379}
+        config = CacheConfig(
+            aiocache_alias="data", max_bytes=1024, aiocache_config={"data": dict(redis)}
+        )
+        CacheGateway.apply_config(config)
+        assert caches.get_config()["data"] == redis
+
+    def test_from_mapping_reads_max_bytes(self) -> None:
+        config = CacheConfig.from_mapping({"max_bytes": "2048"})
+        assert config.max_bytes == 2048
+
+    def test_config_refuses_bounds_below_one(self) -> None:
+        with pytest.raises(ValueError, match="max_bytes"):
+            CacheConfig(max_bytes=0)