feat(cache): add optional module= keyword for per-module shared backend

Author: cassiofariasmachado

src/sap_cloud_sdk/cache/_cache.py

@@ -23,6 +23,7 @@
 from sap_cloud_sdk.cache._config import CacheConfig, get_cache_config
 from sap_cloud_sdk.cache._isolation import build_isolation_key
 from sap_cloud_sdk.cache._lru_backend import InMemoryLRUBackend
+from sap_cloud_sdk.cache._registry import get_module_backend
 from sap_cloud_sdk.cache.exceptions import BackendError
 
 logger = logging.getLogger(__name__)
@@ -40,10 +41,31 @@ class Cache:
             :func:`~sap_cloud_sdk.cache._config.configure_cache` is used.
             The config is snapshotted at construction time — subsequent calls
             to :func:`configure_cache` do not affect an existing ``Cache``.
+        module: Optional logical module name (e.g. ``"agentgateway"``).
+            When given, all ``Cache`` instances with the same *module* name
+            share a single :class:`~sap_cloud_sdk.cache._lru_backend.InMemoryLRUBackend`
+            that lives for the process lifetime. This lets modules that
+            create a new client on every request still benefit from
+            cross-request caching.
+
+            ``max_size`` and ``on_evict`` are taken from the **first**
+            ``Cache`` created for a given *module* name; later callers with
+            different values are silently ignored. Pass ``None`` (the
+            default) to get a per-instance cache backend — nothing is
+            shared.
+
+            An explicit ``CacheConfig(backend=...)`` always takes precedence
+            over *module*.
     """
 
-    def __init__(self, config: CacheConfig | None = None) -> None:
+    def __init__(
+        self,
+        config: CacheConfig | None = None,
+        *,
+        module: str | None = None,
+    ) -> None:
         self._config: CacheConfig = config if config is not None else get_cache_config()
+        self._module: str | None = module
         self._backend = self._resolve_backend()
 
     # ------------------------------------------------------------------
@@ -136,8 +158,19 @@ def reset(self) -> None:
     # ------------------------------------------------------------------
 
     def _resolve_backend(self) -> CacheBackend:
+        # 1. Explicit backend wins (e.g. Redis)
         if self._config.backend is not None:
             return self._config.backend
+
+        # 2. Per-module shared backend, memoized by name
+        if self._module is not None:
+            return get_module_backend(
+                self._module,
+                self._config.max_size,
+                self._config.on_evict,
+            )
+
+        # 3. Fresh per-instance backend
         return InMemoryLRUBackend(
             max_size=self._config.max_size,
             on_evict=self._config.on_evict,

src/sap_cloud_sdk/cache/_registry.py

@@ -0,0 +1,67 @@
+"""Per-module shared backend registry.
+
+SDK modules that create a new client on every request can opt into a
+per-module *shared* backend so that the cache survives across requests.
+This module holds the registry that maps module names to their backends.
+
+Sizing (``max_size``, ``on_evict``) is fixed on the **first** call for a
+given module name; subsequent calls with different values are ignored.
+That is intentional — a module uses one sizing policy and registers its
+backend exactly once at startup.
+
+Private to the cache package; not exported from ``sap_cloud_sdk.cache``.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable
+
+from sap_cloud_sdk.cache._lru_backend import InMemoryLRUBackend
+
+# Module-level registry guarded by a lock so concurrent first-time
+# registrations are safe.
+_lock: threading.Lock = threading.Lock()
+_backends: dict[str, InMemoryLRUBackend] = {}
+
+
+def get_module_backend(
+    name: str,
+    max_size: int,
+    on_evict: Callable[[str, str], None] | None,
+) -> InMemoryLRUBackend:
+    """Return the shared :class:`~sap_cloud_sdk.cache._lru_backend.InMemoryLRUBackend`
+    for *name*, creating it on the first call.
+
+    Args:
+        name: Logical module identifier, e.g. ``"agentgateway"``.
+        max_size: Maximum backend capacity (LRU). Used only on the first
+            call for *name*; ignored on subsequent calls.
+        on_evict: Eviction callback. Used only on the first call for *name*.
+
+    Returns:
+        The singleton :class:`InMemoryLRUBackend` for *name*.
+    """
+    # Fast path — backend already registered.
+    try:
+        return _backends[name]
+    except KeyError:
+        pass
+
+    with _lock:
+        # Re-check under the lock to avoid a race between two first-time callers.
+        if name not in _backends:
+            _backends[name] = InMemoryLRUBackend(max_size=max_size, on_evict=on_evict)
+
+        return _backends[name]
+
+
+def reset_module_backends() -> None:
+    """Clear the registry.  **Test seam only — do not call in production.**
+
+    Removes all per-module backend singletons so that the next call to
+    :func:`get_module_backend` starts fresh.  This is necessary because
+    module-level state persists across test cases.
+    """
+    with _lock:
+        _backends.clear()

src/sap_cloud_sdk/cache/user-guide.md

@@ -120,6 +120,29 @@ The backend interface has exactly four methods and no awareness of tenants, TTL
 
 For a real, in-tree example of how the cache is used, see `XsuaaAuthProvider` in `sap_cloud_sdk.core.protocol.http.models`. It uses `IsolationStrategy.TENANT` to cache OAuth2 sessions per tenant, with TTL derived from the token's `expires_in` field and automatic eviction on secret rotation.
 
+## Per-Module Shared Backend
+
+By default each `Cache` instance gets its own `InMemoryLRUBackend`. That is fine when the same client object is reused across requests, but some modules (e.g. Agent Gateway) create a fresh client on every request. In that case the cache would be empty on each request, defeating its purpose.
+
+Pass `module=` to share a single backend across all `Cache` instances that name the same module:
+
+```python
+from sap_cloud_sdk.cache._cache import Cache
+from sap_cloud_sdk.cache import CacheConfig, IsolationStrategy
+
+# Every time this module creates a new client, it gets the same backend.
+self._cache = Cache(
+    CacheConfig(isolation_strategy=IsolationStrategy.TENANT),
+    module="agentgateway",
+)
+```
+
+The backend is created once (process-scoped, singleton per module name) and reused for the lifetime of the process. Tenant isolation still works normally — the isolation key is derived from the active `RuntimeContext` on every `get`/`set`, so entries are never shared across tenants.
+
+### Sizing and eviction
+
+`max_size` and `on_evict` are taken from the **first** `Cache` created for a given module name. Later callers with different values are silently ignored. This is intentional: a module uses one sizing policy for its backend.
+
 ## API Reference
 
 ### `configure_cache(config: CacheConfig) -> None`

src/sap_cloud_sdk/core/protocol/http/models.py

@@ -83,7 +83,8 @@ def __init__(
         self._config = config_factory()
         self._timeout = timeout
         self._cache: Cache = Cache(
-            CacheConfig(isolation_strategy=IsolationStrategy.TENANT)
+            CacheConfig(isolation_strategy=IsolationStrategy.TENANT),
+            module="core.protocol.http",
         )
 
     def get_session(self, tenant_subdomain: Optional[str] = None) -> OAuth2Session:

tests/cache/unit/test_cache.py

@@ -1,5 +1,6 @@
 """Unit tests for the Cache façade."""
 
+from collections.abc import Generator
 from unittest.mock import MagicMock
 
 import pytest
@@ -8,6 +9,7 @@
 from sap_cloud_sdk.cache._cache import Cache
 from sap_cloud_sdk.cache._config import CacheConfig, configure_cache
 from sap_cloud_sdk.cache._isolation import IsolationStrategy
+from sap_cloud_sdk.cache._registry import reset_module_backends
 from sap_cloud_sdk.core.runtime_context import APP_TENANT_ID, USER_ID, RuntimeContext
 from sap_cloud_sdk.core.runtime_context._context import sdk_context
 from sap_cloud_sdk.cache.exceptions import BackendError
@@ -22,6 +24,18 @@ def _ctx(tenant_id: str | None = None, user_id: str | None = None) -> RuntimeCon
     return RuntimeContext(values)
 
 
+@pytest.fixture(autouse=True)
+def _clear_module_registry() -> Generator[None, None, None]:
+    """Reset the per-module backend registry before every test.
+
+    Module-level singletons persist across test cases, which would cause
+    tests that use ``module=`` to interfere with each other.
+    """
+    reset_module_backends()
+    yield
+    reset_module_backends()
+
+
 class TestCacheGet:
     def test_get_miss_returns_none(self) -> None:
         cache = Cache(CacheConfig())
@@ -195,3 +209,90 @@ def test_full_key_includes_namespace_and_key(self) -> None:
         assert full_key.startswith("destination::")
         assert full_key.endswith("::my-dest")
         assert "tenant-xyz" in full_key
+
+
+class TestCacheModuleBackend:
+    """Tests for the optional ``module=`` keyword on :class:`Cache`."""
+
+    def test_same_module_name_shares_backend(self) -> None:
+        """Two Cache instances with the same module share state."""
+        cfg = CacheConfig(isolation_strategy=IsolationStrategy.TENANT)
+        cache_a = Cache(cfg, module="mymodule")
+        cache_b = Cache(cfg, module="mymodule")
+
+        with sdk_context(_ctx(tenant_id="t1")):
+            cache_a.set("ns", "key", "shared-value", ttl_seconds=60)
+            assert cache_b.get("ns", "key") == "shared-value"
+
+    def test_different_module_names_are_isolated(self) -> None:
+        """Two Cache instances with different module names do not share state."""
+        cfg = CacheConfig(isolation_strategy=IsolationStrategy.TENANT)
+        cache_x = Cache(cfg, module="module-x")
+        cache_y = Cache(cfg, module="module-y")
+
+        with sdk_context(_ctx(tenant_id="t1")):
+            cache_x.set("ns", "key", "value-x", ttl_seconds=60)
+            assert cache_y.get("ns", "key") is None
+
+    def test_no_module_gives_fresh_per_instance_backend(self) -> None:
+        """Without module=, each Cache instance has its own backend (legacy behavior)."""
+        cfg = CacheConfig(isolation_strategy=IsolationStrategy.TENANT)
+        cache_1 = Cache(cfg)
+        cache_2 = Cache(cfg)
+
+        with sdk_context(_ctx(tenant_id="t1")):
+            cache_1.set("ns", "key", "value-1", ttl_seconds=60)
+            # cache_2 has a separate backend, so it must not see cache_1's entry.
+            assert cache_2.get("ns", "key") is None
+
+    def test_explicit_backend_overrides_module(self) -> None:
+        """CacheConfig(backend=...) wins over module=."""
+        explicit_backend = MagicMock(spec=CacheBackend)
+        explicit_backend.get.return_value = "from-explicit"
+        cache = Cache(CacheConfig(backend=explicit_backend), module="mymodule")
+
+        with sdk_context(_ctx(tenant_id="t1")):
+            result = cache.get("ns", "key")
+
+        explicit_backend.get.assert_called_once()
+        assert result == "from-explicit"
+
+    def test_module_backend_survives_across_simulated_requests(self) -> None:
+        """Simulate per-request client creation: backend must carry state across."""
+        cfg = CacheConfig(isolation_strategy=IsolationStrategy.TENANT)
+
+        # First "request": create a client and populate the cache.
+        cache_req1 = Cache(cfg, module="agentgateway")
+        with sdk_context(_ctx(tenant_id="t1")):
+            cache_req1.set("token", "svc-url", "my-token", ttl_seconds=60)
+
+        # Second "request": a brand-new client must still find the entry.
+        cache_req2 = Cache(cfg, module="agentgateway")
+        with sdk_context(_ctx(tenant_id="t1")):
+            assert cache_req2.get("token", "svc-url") == "my-token"
+
+    def test_module_backend_tenant_isolation(self) -> None:
+        """Shared module backend must still isolate across tenants."""
+        cfg = CacheConfig(isolation_strategy=IsolationStrategy.TENANT)
+        cache = Cache(cfg, module="agentgateway")
+
+        with sdk_context(_ctx(tenant_id="tenant-a")):
+            cache.set("token", "svc", "token-a", ttl_seconds=60)
+        with sdk_context(_ctx(tenant_id="tenant-b")):
+            assert cache.get("token", "svc") is None
+
+    def test_module_backend_sizing_from_first_caller(self) -> None:
+        """max_size is fixed on the first Cache created for a module."""
+        # First caller: max_size=2
+        cache_first = Cache(CacheConfig(max_size=2), module="sized-module")
+        # Second caller: max_size=500 (ignored — backend already exists)
+        cache_second = Cache(CacheConfig(max_size=500), module="sized-module")
+
+        # Both should share the same backend (capped at 2).
+        with sdk_context(_ctx(tenant_id="t1")):
+            cache_first.set("ns", "k1", "v1", ttl_seconds=60)
+            cache_first.set("ns", "k2", "v2", ttl_seconds=60)
+            # Third entry evicts the oldest (LRU) when max_size=2.
+            cache_first.set("ns", "k3", "v3", ttl_seconds=60)
+            # k3 is always present; exactly one of k1/k2 was evicted.
+            assert cache_second.get("ns", "k3") == "v3"