pz-cli 5.0.0__py3-none-any.whl

pz_foundation/kv/cache.py

@@ -0,0 +1,1166 @@
+from __future__ import annotations
+
+import contextlib
+import os
+from dataclasses import dataclass, field, replace
+from functools import lru_cache
+from pathlib import Path
+from threading import RLock
+import asyncio
+import json
+import time
+from concurrent.futures import Future
+from threading import Event, Thread
+from typing import Any, Callable, Generic, Iterable, Optional, Sequence, TypeVar
+from urllib.parse import unquote, urlparse
+
+try:
+    import redis
+except Exception:  # pragma: no cover
+    redis = None  # type: ignore
+
+import pz_settings_center.public as settings_center
+from ..observability import get_logger
+from .redis_manager import RedisConfig, RedisManager
+
+
+logger = get_logger(__name__)
+
+
+def _resolved_settings(*, project_dir: str | os.PathLike[str] | None = None):
+    if project_dir is None:
+        return settings_center.settings
+    return settings_center.resolve_settings(project_dir=str(Path(project_dir).resolve()))
+
+
+def _project_settings(*, project_dir: str | os.PathLike[str] | None = None):
+    try:
+        return _resolved_settings(project_dir=project_dir).project
+    except Exception:
+        return None
+
+
+def _foundation_settings_section(
+    name: str,
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+):
+    section_name = str(name or "").strip()
+    try:
+        resolved = _resolved_settings(project_dir=project_dir)
+        if hasattr(resolved, "app_settings"):
+            foundation_payload = resolved.app_settings("pz_foundation")
+            if isinstance(foundation_payload, dict):
+                section = foundation_payload.get(section_name, {})
+                if section not in (None, {}):
+                    return section
+        foundation_settings = getattr(resolved, "pz_foundation", None)
+        if isinstance(foundation_settings, dict):
+            return foundation_settings.get(section_name, {})
+        if foundation_settings is None:
+            return {}
+        return getattr(foundation_settings, section_name, {})
+    except Exception:
+        return {}
+
+
+@dataclass(frozen=True, slots=True)
+class FoundationRedisSettings:
+    enabled: bool = False
+    host: str = ""
+    port: int = 6379
+    db: int = 0
+    password: str | None = None
+    url: str | None = None
+    service: str = "mymaster"
+    allow_cluster: bool = False
+    connect_timeout_seconds: float = 1.0
+    socket_timeout_seconds: float = 1.0
+    operation_max_attempts: int = 2
+    connection_retry_attempts: int = 0
+    retry_base_delay_seconds: float = 0.05
+    retry_max_delay_seconds: float = 0.2
+    acquire_failure_cooldown_seconds: float = 2.0
+    health_failure_cooldown_seconds: float = 2.0
+
+
+class FoundationRedisUnavailable(RuntimeError):
+    """Raised when a required foundation Redis capability is disabled, misconfigured, or unavailable."""
+
+
+def _split_redis_host_entry(raw_entry: str, default_port: int) -> tuple[str, int]:
+    entry = str(raw_entry or "").strip()
+    if not entry:
+        return "", default_port
+    if entry.startswith("["):
+        closing = entry.find("]")
+        if closing > 0:
+            host = entry[1:closing].strip()
+            remainder = entry[closing + 1 :].strip()
+            if remainder.startswith(":"):
+                try:
+                    return host, int(remainder[1:] or default_port)
+                except Exception:
+                    return host, default_port
+            return host, default_port
+    if entry.count(":") == 1:
+        host, raw_port = entry.rsplit(":", 1)
+        try:
+            return host.strip(), int(raw_port or default_port)
+        except Exception:
+            return host.strip(), default_port
+    return entry, default_port
+
+
+def _parse_redis_endpoints(raw: str | None, default_port: int) -> tuple[tuple[str, int], ...]:
+    endpoints: list[tuple[str, int]] = []
+    for part in str(raw or "").split(","):
+        host, port = _split_redis_host_entry(part, default_port)
+        if not host:
+            continue
+        endpoints.append((host, port))
+    return tuple(endpoints)
+
+
+def _split_redis_netloc(netloc: str) -> tuple[str, str]:
+    text = str(netloc or "").strip()
+    if "@" not in text:
+        return "", text
+    userinfo, hostspec = text.rsplit("@", 1)
+    return userinfo, hostspec
+
+
+def _parse_redis_url_password(userinfo: str) -> str | None:
+    text = str(userinfo or "")
+    if ":" not in text:
+        return None
+    _username, _separator, raw_password = text.partition(":")
+    if not raw_password:
+        return None
+    return unquote(raw_password)
+
+
+def _build_redis_config_from_resolved_values(
+    *,
+    host: str,
+    port: int,
+    db: int,
+    password: str | None,
+    service: str,
+    allow_cluster: bool,
+    connect_timeout_seconds: float,
+    socket_timeout_seconds: float,
+    operation_max_attempts: int,
+    connection_retry_attempts: int,
+    retry_base_delay_seconds: float,
+    retry_max_delay_seconds: float,
+    acquire_failure_cooldown_seconds: float,
+    health_failure_cooldown_seconds: float,
+) -> RedisConfig:
+    endpoints = _parse_redis_endpoints(host, int(port or 6379))
+    base_kwargs = {
+        "db": db,
+        "password": password,
+        "sentinel_service": str(service or "mymaster") or "mymaster",
+        "allow_cluster": bool(allow_cluster),
+        "connect_timeout_seconds": connect_timeout_seconds,
+        "socket_timeout_seconds": socket_timeout_seconds,
+        "operation_max_attempts": operation_max_attempts,
+        "connection_retry_attempts": connection_retry_attempts,
+        "retry_base_delay_seconds": retry_base_delay_seconds,
+        "retry_max_delay_seconds": retry_max_delay_seconds,
+        "acquire_failure_cooldown_seconds": acquire_failure_cooldown_seconds,
+        "health_failure_cooldown_seconds": health_failure_cooldown_seconds,
+    }
+    if len(endpoints) > 1:
+        primary_host, primary_port = endpoints[0]
+        return RedisConfig(
+            host=primary_host,
+            port=primary_port,
+            sentinel_hosts=endpoints,
+            **base_kwargs,
+        )
+    if len(endpoints) == 1:
+        primary_host, primary_port = endpoints[0]
+        return RedisConfig(
+            host=primary_host,
+            port=primary_port,
+            **base_kwargs,
+        )
+    return RedisConfig(
+        host="",
+        port=int(port or 6379),
+        **base_kwargs,
+    )
+
+
+@dataclass(slots=True)
+class InMemoryFoundationCache:
+    _lock: RLock = field(default_factory=RLock)
+    _strings: dict[str, str] = field(default_factory=dict)
+    _lists: dict[str, list[str]] = field(default_factory=dict)
+    _sets: dict[str, set[str]] = field(default_factory=dict)
+
+    def get(self, key: str) -> str | None:
+        with self._lock:
+            return self._strings.get(key)
+
+    def mget(self, keys: Iterable[str]) -> list[str | None]:
+        return [self.get(str(key)) for key in keys]
+
+    def set(
+        self,
+        key: str,
+        value: object,
+        *,
+        ttl_seconds: int | None = None,
+        ex: int | None = None,
+        nx: bool = False,
+    ) -> bool:
+        del ttl_seconds, ex
+        with self._lock:
+            if nx and key in self._strings:
+                return False
+            self._strings[key] = str(value)
+            return True
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._strings.pop(key, None)
+            self._lists.pop(key, None)
+            self._sets.pop(key, None)
+
+    def delete_if_value_matches(self, key: str, expected_value: object) -> bool:
+        with self._lock:
+            if self._strings.get(key) != str(expected_value):
+                return False
+            self._strings.pop(key, None)
+            return True
+
+    def sadd(self, key: str, *values: object) -> int:
+        with self._lock:
+            payload = self._sets.setdefault(key, set())
+            before = len(payload)
+            payload.update(str(value) for value in values)
+            return len(payload) - before
+
+    def smembers(self, key: str) -> set[str]:
+        with self._lock:
+            return set(self._sets.get(key, set()))
+
+    def rpush(self, key: str, *values: object) -> int:
+        with self._lock:
+            payload = self._lists.setdefault(key, [])
+            payload.extend(str(value) for value in values)
+            return len(payload)
+
+    def lrange(self, key: str, start: int, end: int) -> list[str]:
+        with self._lock:
+            payload = list(self._lists.get(key, []))
+        if end == -1:
+            return payload[start:]
+        return payload[start : end + 1]
+
+
+@dataclass(slots=True)
+class RedisFoundationCache:
+    settings: FoundationRedisSettings
+    _client: Any = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._client = self._build_client()
+
+    def get(self, key: str) -> str | None:
+        value = self._client.get(key)
+        if value is None:
+            return None
+        return str(value)
+
+    def mget(self, keys: Iterable[str]) -> list[str | None]:
+        values = self._client.mget(list(keys))
+        return [None if value is None else str(value) for value in values]
+
+    def set(
+        self,
+        key: str,
+        value: object,
+        *,
+        ttl_seconds: int | None = None,
+        ex: int | None = None,
+        nx: bool = False,
+    ) -> bool:
+        ttl = ex if ex is not None else ttl_seconds
+        result = self._client.set(key, str(value), ex=ttl, nx=nx)
+        return bool(result)
+
+    def delete(self, key: str) -> None:
+        self._client.delete(key)
+
+    def delete_if_value_matches(self, key: str, expected_value: object) -> bool:
+        result = self._client.eval(
+            "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
+            1,
+            key,
+            str(expected_value),
+        )
+        return bool(result)
+
+    def sadd(self, key: str, *values: object) -> int:
+        return int(self._client.sadd(key, *(str(value) for value in values)))
+
+    def smembers(self, key: str) -> set[str]:
+        return {str(item) for item in self._client.smembers(key)}
+
+    def rpush(self, key: str, *values: object) -> int:
+        return int(self._client.rpush(key, *(str(value) for value in values)))
+
+    def lrange(self, key: str, start: int, end: int) -> list[str]:
+        return [str(item) for item in self._client.lrange(key, start, end)]
+
+    def _build_client(self) -> Any:
+        if redis is None:
+            raise RuntimeError("redis package is required for RedisFoundationCache")
+        if not self.settings.enabled:
+            raise RuntimeError("foundation redis is disabled")
+        if self.settings.url:
+            return redis.Redis.from_url(
+                self.settings.url,
+                decode_responses=True,
+                socket_timeout=float(self.settings.socket_timeout_seconds or 1.0),
+                socket_connect_timeout=float(self.settings.connect_timeout_seconds or 1.0),
+                retry_on_timeout=False,
+            )
+        if not self.settings.host.strip():
+            raise RuntimeError("foundation redis host is not configured")
+        return redis.Redis(
+            host=self.settings.host,
+            port=self.settings.port,
+            db=self.settings.db,
+            password=self.settings.password,
+            decode_responses=True,
+            socket_timeout=float(self.settings.socket_timeout_seconds or 1.0),
+            socket_connect_timeout=float(self.settings.connect_timeout_seconds or 1.0),
+            retry_on_timeout=False,
+        )
+
+    def ping(self) -> bool:
+        return bool(self._client.ping())
+
+
+@dataclass
+class _L1Item:
+    value: Any
+    expires_at: float
+
+
+@dataclass(frozen=True, slots=True)
+class CacheSnapshot:
+    json_values: dict[str, Any | None]
+    version_values: dict[str, int]
+
+    def get_json(self, key: str) -> Any | None:
+        return self.json_values.get(key)
+
+    def get_version(self, name: str) -> int:
+        value = self.version_values.get(name, 0)
+        try:
+            return int(value)
+        except Exception:
+            return 0
+
+
+class CacheService:
+    def __init__(self, redis_manager: Any) -> None:
+        self._redis_manager = redis_manager
+        self._version_prefix = "cache:version:"
+        self._lock_prefix = "lock:"
+        self._l1: dict[str, _L1Item] = {}
+        self._l1_lock = asyncio.Lock()
+
+    def _l1_get(self, key: str) -> Any | None:
+        item = self._l1.get(key)
+        if not item:
+            return None
+        if item.expires_at and item.expires_at < time.time():
+            self._l1.pop(key, None)
+            return None
+        return item.value
+
+    def _l1_set(self, key: str, value: Any, ttl: Optional[int]) -> None:
+        expires_at = 0.0 if not ttl else time.time() + int(ttl)
+        self._l1[key] = _L1Item(value=value, expires_at=expires_at)
+
+    def _l1_invalidate(self, keys: Sequence[str]) -> None:
+        for key in keys:
+            self._l1.pop(key, None)
+
+    async def get_json(self, key: str) -> Any | None:
+        cached = self._l1_get(key)
+        if cached is not None:
+            return cached
+        try:
+            client = await self._redis_manager.get_connection()
+            raw = await client.get(key)
+            if raw is None:
+                return None
+            parsed = json.loads(raw)
+            ttl = await client.ttl(key)
+            ttl = 0 if ttl < 0 else int(ttl)
+            self._l1_set(key, parsed, ttl or None)
+            return parsed
+        except Exception as exc:
+            logger.debug("cache.get_json(%s) failed: %s", key, exc)
+            raise
+
+    async def read_snapshot(
+        self,
+        *,
+        json_keys: Sequence[str] = (),
+        version_names: Sequence[str] = (),
+    ) -> CacheSnapshot:
+        json_values: dict[str, Any | None] = {str(key): None for key in json_keys}
+        version_values: dict[str, int] = {str(name): 0 for name in version_names}
+        targets: list[tuple[str, str]] = []
+        raw_keys: list[str] = []
+
+        for key in dict.fromkeys(str(key) for key in json_keys):
+            cached = self._l1_get(key)
+            if cached is not None:
+                json_values[key] = cached
+                continue
+            targets.append(("json", key))
+            raw_keys.append(key)
+        for name in dict.fromkeys(str(name) for name in version_names):
+            targets.append(("version", name))
+            raw_keys.append(self._version_prefix + name)
+
+        if not raw_keys:
+            return CacheSnapshot(json_values=json_values, version_values=version_values)
+
+        try:
+            client = await self._redis_manager.get_connection()
+            raw_values = await client.mget(raw_keys)
+            for target, raw in zip(targets, raw_values):
+                kind, name = target
+                if kind == "json":
+                    json_values[name] = None if raw is None else json.loads(raw)
+                else:
+                    version_values[name] = 0 if raw is None else int(raw)
+            return CacheSnapshot(json_values=json_values, version_values=version_values)
+        except Exception as exc:
+            logger.debug("cache.read_snapshot(json_keys=%s, version_names=%s) failed: %s", json_keys, version_names, exc)
+            raise
+
+    async def set_json(self, key: str, value: Any, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None:
+        try:
+            client = await self._redis_manager.get_connection()
+            payload = json.dumps(value, ensure_ascii=False)
+            if ttl and ttl > 0:
+                await client.setex(key, int(ttl), payload)
+            else:
+                await client.set(key, payload)
+            for tag in tags or []:
+                tag_key = f"cache:tag:{tag}"
+                await client.sadd(tag_key, key)
+                if ttl and ttl > 0:
+                    await client.expire(tag_key, int(ttl))
+            self._l1_set(key, value, ttl)
+        except Exception as exc:
+            logger.debug("cache.set_json(%s) failed: %s", key, exc)
+            raise
+
+    async def invalidate(self, *, keys: Optional[Sequence[str]] = None, tags: Optional[Sequence[str]] = None) -> None:
+        keys = list(keys or [])
+        try:
+            client = await self._redis_manager.get_connection()
+            for tag in tags or []:
+                tag_key = f"cache:tag:{tag}"
+                members = await client.smembers(tag_key)
+                if members:
+                    keys.extend(list(members))
+                await client.delete(tag_key)
+            if keys:
+                await client.delete(*set(keys))
+        except Exception as exc:
+            logger.debug("cache.invalidate(tags=%s, keys=%s) failed: %s", tags, keys, exc)
+            raise
+        self._l1_invalidate(set(keys))
+
+    async def get_version(self, name: str) -> int:
+        try:
+            client = await self._redis_manager.get_connection()
+            raw = await client.get(self._version_prefix + name)
+            return 0 if raw is None else int(raw)
+        except Exception as exc:
+            logger.debug("cache.get_version(%s) failed: %s", name, exc)
+            raise
+
+    async def bump_version(self, name: str) -> int:
+        try:
+            client = await self._redis_manager.get_connection()
+            return int(await client.incr(self._version_prefix + name))
+        except Exception as exc:
+            logger.debug("cache.bump_version(%s) failed: %s", name, exc)
+            raise
+
+    async def try_acquire_lock(self, name: str, ttl: int = 15) -> bool:
+        try:
+            client = await self._redis_manager.get_connection()
+            return bool(await client.set(self._lock_prefix + name, "1", ex=int(ttl), nx=True))
+        except Exception as exc:
+            logger.debug("cache.try_acquire_lock(%s) failed: %s", name, exc)
+            raise
+
+
+class SyncRedisAdapter:
+    """Run async redis-manager commands on a dedicated event-loop thread."""
+
+    def __init__(self, redis_manager: Any) -> None:
+        if redis_manager is None:
+            raise ValueError("SyncRedisAdapter requires an explicit redis manager")
+        self._redis_manager = redis_manager
+        self._ready = Event()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread = Thread(target=self._run_loop, name="foundation-sync-cache", daemon=True)
+        self._thread.start()
+        self._ready.wait()
+
+    def _run_loop(self) -> None:
+        loop = asyncio.new_event_loop()
+        self._loop = loop
+        asyncio.set_event_loop(loop)
+        self._ready.set()
+        loop.run_forever()
+        loop.close()
+
+    async def _invoke(self, method_name: str, *args: Any, **kwargs: Any) -> Any:
+        client = await self._redis_manager.get_connection()
+        method = getattr(client, method_name)
+        return await method(*args, **kwargs)
+
+    def call(self, method_name: str, *args: Any, **kwargs: Any) -> Any:
+        if self._loop is None:
+            raise RuntimeError("sync redis adapter loop is not ready")
+        future: Future[Any] = asyncio.run_coroutine_threadsafe(
+            self._invoke(method_name, *args, **kwargs),
+            self._loop,
+        )
+        return future.result()
+
+    def __getattr__(self, name: str) -> Any:
+        def caller(*args: Any, **kwargs: Any) -> Any:
+            return self.call(name, *args, **kwargs)
+
+        return caller
+
+    def close(self) -> None:
+        loop = self._loop
+        if loop is None or loop.is_closed():
+            return
+        with contextlib.suppress(Exception):
+            future = asyncio.run_coroutine_threadsafe(
+                self._redis_manager.reset_connection(),
+                loop,
+            )
+            future.result(timeout=1.0)
+        loop.call_soon_threadsafe(loop.stop)
+        self._thread.join(timeout=1.0)
+
+
+class SyncCacheService:
+    def __init__(self, backend: Any) -> None:
+        self._backend = backend
+        self._version_prefix = "cache:version:"
+        self._lock_prefix = "lock:"
+        self._l1: dict[str, _L1Item] = {}
+
+    def _l1_get(self, key: str) -> Any | None:
+        item = self._l1.get(key)
+        if not item:
+            return None
+        if item.expires_at and item.expires_at < time.time():
+            self._l1.pop(key, None)
+            return None
+        return item.value
+
+    def _l1_set(self, key: str, value: Any, ttl: Optional[int]) -> None:
+        expires_at = 0.0 if not ttl else time.time() + int(ttl)
+        self._l1[key] = _L1Item(value=value, expires_at=expires_at)
+
+    def _l1_invalidate(self, keys: Sequence[str]) -> None:
+        for key in keys:
+            self._l1.pop(key, None)
+
+    def get_json(self, key: str) -> Any | None:
+        cached = self._l1_get(key)
+        if cached is not None:
+            return cached
+        try:
+            raw = self._backend.get(key)
+            if raw is None:
+                return None
+            parsed = json.loads(raw)
+            ttl_reader = getattr(self._backend, "ttl", None)
+            ttl = int(ttl_reader(key)) if callable(ttl_reader) else 0
+            ttl = 0 if ttl < 0 else ttl
+            self._l1_set(key, parsed, ttl or None)
+            return parsed
+        except Exception as exc:
+            logger.debug("sync cache.get_json(%s) failed: %s", key, exc)
+            return None
+
+    def read_snapshot(
+        self,
+        *,
+        json_keys: Sequence[str] = (),
+        version_names: Sequence[str] = (),
+    ) -> CacheSnapshot:
+        json_values: dict[str, Any | None] = {str(key): None for key in json_keys}
+        version_values: dict[str, int] = {str(name): 0 for name in version_names}
+        targets: list[tuple[str, str]] = []
+        raw_keys: list[str] = []
+
+        for key in dict.fromkeys(str(key) for key in json_keys):
+            cached = self._l1_get(key)
+            if cached is not None:
+                json_values[key] = cached
+                continue
+            targets.append(("json", key))
+            raw_keys.append(key)
+        for name in dict.fromkeys(str(name) for name in version_names):
+            targets.append(("version", name))
+            raw_keys.append(self._version_prefix + name)
+
+        if not raw_keys:
+            return CacheSnapshot(json_values=json_values, version_values=version_values)
+
+        try:
+            raw_values = self._backend.mget(raw_keys)
+            for target, raw in zip(targets, raw_values):
+                kind, name = target
+                if kind == "json":
+                    json_values[name] = None if raw is None else json.loads(raw)
+                else:
+                    version_values[name] = 0 if raw is None else int(raw)
+        except Exception as exc:
+            logger.debug(
+                "sync cache.read_snapshot(json_keys=%s, version_names=%s) failed: %s",
+                json_keys,
+                version_names,
+                exc,
+            )
+        return CacheSnapshot(json_values=json_values, version_values=version_values)
+
+    def set_json(self, key: str, value: Any, ttl: Optional[int] = None, tags: Optional[Iterable[str]] = None) -> None:
+        try:
+            payload = json.dumps(value, ensure_ascii=False)
+            ttl_value = int(ttl) if ttl and ttl > 0 else None
+            if ttl_value is not None:
+                setex = getattr(self._backend, "setex", None)
+                if callable(setex):
+                    setex(key, ttl_value, payload)
+                else:
+                    self._backend.set(key, payload, ex=ttl_value)
+            else:
+                self._backend.set(key, payload)
+            for tag in tags or ():
+                tag_key = f"cache:tag:{tag}"
+                self._backend.sadd(tag_key, key)
+                expire = getattr(self._backend, "expire", None)
+                if ttl_value is not None and callable(expire):
+                    expire(tag_key, ttl_value)
+            self._l1_set(key, value, ttl)
+        except Exception as exc:
+            logger.debug("sync cache.set_json(%s) failed: %s", key, exc)
+            self._l1_set(key, value, ttl)
+
+    def invalidate(self, *, keys: Optional[Sequence[str]] = None, tags: Optional[Sequence[str]] = None) -> None:
+        invalidated_keys = list(keys or ())
+        try:
+            for tag in tags or ():
+                tag_key = f"cache:tag:{tag}"
+                members = self._backend.smembers(tag_key)
+                if members:
+                    invalidated_keys.extend(list(members))
+                self._backend.delete(tag_key)
+            if invalidated_keys:
+                self._backend.delete(*tuple(set(invalidated_keys)))
+        except Exception as exc:
+            logger.debug("sync cache.invalidate(tags=%s, keys=%s) failed: %s", tags, invalidated_keys, exc)
+        self._l1_invalidate(set(invalidated_keys))
+
+    def get_version(self, name: str) -> int:
+        try:
+            raw = self._backend.get(self._version_prefix + str(name))
+            return 0 if raw is None else int(raw)
+        except Exception as exc:
+            logger.debug("sync cache.get_version(%s) failed: %s", name, exc)
+            return 0
+
+    def bump_version(self, name: str) -> int:
+        try:
+            return int(self._backend.incr(self._version_prefix + str(name)))
+        except Exception as exc:
+            logger.debug("sync cache.bump_version(%s) failed: %s", name, exc)
+            return 0
+
+    def close(self) -> None:
+        closer = getattr(self._backend, "close", None)
+        if callable(closer):
+            with contextlib.suppress(Exception):
+                closer()
+
+
+T = TypeVar("T")
+
+
+class _LazyAccessor(Generic[T]):
+    __slots__ = ("_factory", "_instance")
+
+    def __init__(self, factory: Callable[[], T]) -> None:
+        object.__setattr__(self, "_factory", factory)
+        object.__setattr__(self, "_instance", None)
+
+    def _get_instance(self) -> T:
+        inst = object.__getattribute__(self, "_instance")
+        if inst is None:
+            inst = object.__getattribute__(self, "_factory")()
+            object.__setattr__(self, "_instance", inst)
+        return inst  # type: ignore[return-value]
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._get_instance(), name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name in {"_factory", "_instance"}:
+            object.__setattr__(self, name, value)
+            return
+        setattr(self._get_instance(), name, value)
+
+    def __repr__(self) -> str:
+        inst = object.__getattribute__(self, "_instance")
+        if inst is None:
+            return "<lazy cache service proxy>"
+        return repr(inst)
+
+
+_CACHE_SINGLETONS: dict[str, RedisFoundationCache] = {}
+
+
+def load_foundation_redis_settings(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+) -> FoundationRedisSettings:
+    return _resolve_foundation_redis_settings(project_dir=project_dir)
+
+
+def _redis_binding_configured(settings: FoundationRedisSettings) -> bool:
+    if not settings.enabled:
+        return False
+    return bool(str(settings.url or "").strip() or str(settings.host or "").strip())
+
+
+def describe_foundation_redis_binding(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+) -> dict[str, Any]:
+    resolved = settings or _resolve_foundation_redis_settings(project_dir=project_dir)
+    configured = _redis_binding_configured(resolved)
+    backend = "redis" if configured else "none"
+    return {
+        "enabled": bool(resolved.enabled),
+        "configured": configured,
+        "backend": backend,
+        "operational": False,
+        "degraded": False,
+        "ready": False,
+        "error": None,
+        "host": resolved.host,
+        "port": resolved.port,
+        "db": resolved.db,
+        "url": resolved.url,
+        "probe_deferred": True,
+    }
+
+
+def probe_foundation_redis_binding(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+    capability_name: str = "foundation redis",
+) -> dict[str, Any]:
+    status = describe_foundation_redis_binding(project_dir=project_dir, settings=settings)
+    if not status["enabled"] or not status["configured"]:
+        status["probe_deferred"] = False
+        return status
+    try:
+        cache = get_required_foundation_cache(
+            project_dir=project_dir,
+            settings=settings,
+            capability_name=capability_name,
+        )
+        ready = bool(cache.ping())
+        status["ready"] = ready
+        status["operational"] = ready
+        status["probe_deferred"] = False
+        return status
+    except Exception as exc:
+        status["error"] = str(exc)
+        status["probe_deferred"] = False
+        return status
+
+
+def _resolve_foundation_redis_settings(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+) -> FoundationRedisSettings:
+    redis_payload = _redis_snapshot(project_dir=project_dir)
+    url = _read_str(redis_payload, "url")
+    host = _read_str(redis_payload, "host")
+    port = _read_int(redis_payload, "port", 6379)
+    db = _read_int(redis_payload, "db", 0)
+    password = _read_optional_str(redis_payload, "password")
+    enabled = _read_bool_value(redis_payload, "enabled", False)
+    service = _read_str(redis_payload, "service") or "mymaster"
+    allow_cluster = _read_bool_value(redis_payload, "allow_cluster", False)
+    connect_timeout_seconds = _read_float(redis_payload, "connect_timeout_seconds", 1.0)
+    socket_timeout_seconds = _read_float(redis_payload, "socket_timeout_seconds", 1.0)
+    operation_max_attempts = _read_int(redis_payload, "operation_max_attempts", 2)
+    connection_retry_attempts = _read_int(redis_payload, "connection_retry_attempts", 0)
+    retry_base_delay_seconds = _read_float(redis_payload, "retry_base_delay_seconds", 0.05)
+    retry_max_delay_seconds = _read_float(redis_payload, "retry_max_delay_seconds", 0.2)
+    acquire_failure_cooldown_seconds = _read_float(redis_payload, "acquire_failure_cooldown_seconds", 2.0)
+    health_failure_cooldown_seconds = _read_float(redis_payload, "health_failure_cooldown_seconds", 2.0)
+    return FoundationRedisSettings(
+        enabled=enabled,
+        host=host,
+        port=port,
+        db=db,
+        password=password,
+        url=url,
+        service=service,
+        allow_cluster=allow_cluster,
+        connect_timeout_seconds=connect_timeout_seconds,
+        socket_timeout_seconds=socket_timeout_seconds,
+        operation_max_attempts=operation_max_attempts,
+        connection_retry_attempts=connection_retry_attempts,
+        retry_base_delay_seconds=retry_base_delay_seconds,
+        retry_max_delay_seconds=retry_max_delay_seconds,
+        acquire_failure_cooldown_seconds=acquire_failure_cooldown_seconds,
+        health_failure_cooldown_seconds=health_failure_cooldown_seconds,
+    )
+
+
+def get_foundation_cache(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+) -> RedisFoundationCache:
+    resolved_settings = settings or _resolve_foundation_redis_settings(project_dir=project_dir)
+    key = _cache_key(resolved_settings)
+    cache = _CACHE_SINGLETONS.get(key)
+    if cache is None:
+        cache = RedisFoundationCache(resolved_settings)
+        _CACHE_SINGLETONS[key] = cache
+    return cache
+
+
+def get_required_foundation_cache(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+    capability_name: str = "foundation redis",
+) -> RedisFoundationCache:
+    resolved_settings = settings or _resolve_foundation_redis_settings(project_dir=project_dir)
+    capability_label = str(capability_name or "foundation redis").strip() or "foundation redis"
+    if not resolved_settings.enabled:
+        raise FoundationRedisUnavailable(f"{capability_label} is disabled")
+    if not str(resolved_settings.url or resolved_settings.host or "").strip():
+        raise FoundationRedisUnavailable(f"{capability_label} is not configured")
+    try:
+        return get_foundation_cache(settings=resolved_settings)
+    except FoundationRedisUnavailable:
+        raise
+    except Exception as exc:
+        raise FoundationRedisUnavailable(f"{capability_label} is unavailable") from exc
+
+
+def get_foundation_redis_manager(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+) -> RedisManager:
+    resolved_settings = settings or _resolve_foundation_redis_settings(project_dir=project_dir)
+    return RedisManager(build_foundation_redis_config(resolved_settings))
+
+
+def build_required_foundation_redis_config(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+    capability_name: str = "foundation redis",
+    decode_responses: bool = True,
+) -> RedisConfig:
+    resolved_settings = settings or _resolve_foundation_redis_settings(project_dir=project_dir)
+    capability_label = str(capability_name or "foundation redis").strip() or "foundation redis"
+    if not resolved_settings.enabled:
+        raise FoundationRedisUnavailable(f"{capability_label} is disabled")
+    if not str(resolved_settings.url or resolved_settings.host or "").strip():
+        raise FoundationRedisUnavailable(f"{capability_label} is not configured")
+    return replace(
+        build_foundation_redis_config(resolved_settings),
+        decode_responses=bool(decode_responses),
+    )
+
+
+@lru_cache(maxsize=32)
+def _cached_required_foundation_redis_manager(
+    project_dir: str,
+    capability_name: str,
+    decode_responses: bool,
+) -> RedisManager:
+    return RedisManager(
+        build_required_foundation_redis_config(
+            project_dir=project_dir,
+            capability_name=capability_name,
+            decode_responses=decode_responses,
+        )
+    )
+
+
+def get_required_foundation_redis_manager(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+    capability_name: str = "foundation redis",
+    decode_responses: bool = True,
+) -> RedisManager:
+    if settings is not None:
+        return RedisManager(
+            build_required_foundation_redis_config(
+                settings=settings,
+                capability_name=capability_name,
+                decode_responses=decode_responses,
+            )
+        )
+    resolved_project_dir = "" if project_dir is None else str(Path(project_dir).resolve())
+    return _cached_required_foundation_redis_manager(
+        resolved_project_dir,
+        str(capability_name or "foundation redis"),
+        bool(decode_responses),
+    )
+
+
+async def get_required_foundation_redis_connection(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+    capability_name: str = "foundation redis",
+    decode_responses: bool = True,
+):
+    manager = get_required_foundation_redis_manager(
+        project_dir=project_dir,
+        settings=settings,
+        capability_name=capability_name,
+        decode_responses=decode_responses,
+    )
+    return await manager.get_connection()
+
+
+def build_foundation_redis_config(settings: FoundationRedisSettings) -> RedisConfig:
+    host = settings.host
+    port = settings.port
+    db = settings.db
+    password = settings.password
+    if settings.url:
+        parsed = urlparse(settings.url)
+        userinfo, hostspec = _split_redis_netloc(parsed.netloc)
+        if hostspec:
+            host = hostspec
+        parsed_password = _parse_redis_url_password(userinfo)
+        if parsed_password is not None:
+            password = parsed_password
+        if parsed.path and parsed.path != "/":
+            with_value = parsed.path.removeprefix("/")
+            if with_value.isdigit():
+                db = int(with_value)
+    return _build_redis_config_from_resolved_values(
+        host=host or "",
+        port=port,
+        db=db,
+        password=password,
+        service=settings.service,
+        allow_cluster=settings.allow_cluster,
+        connect_timeout_seconds=settings.connect_timeout_seconds,
+        socket_timeout_seconds=settings.socket_timeout_seconds,
+        operation_max_attempts=settings.operation_max_attempts,
+        connection_retry_attempts=settings.connection_retry_attempts,
+        retry_base_delay_seconds=settings.retry_base_delay_seconds,
+        retry_max_delay_seconds=settings.retry_max_delay_seconds,
+        acquire_failure_cooldown_seconds=settings.acquire_failure_cooldown_seconds,
+        health_failure_cooldown_seconds=settings.health_failure_cooldown_seconds,
+    )
+
+
+def describe_foundation_redis_binding(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+) -> dict[str, Any]:
+    resolved = settings or load_foundation_redis_settings(project_dir=project_dir)
+    configured = bool((resolved.url or "").strip() or (resolved.host or "").strip())
+    return {
+        "enabled": bool(resolved.enabled),
+        "configured": configured,
+        "backend": "redis" if resolved.enabled and configured else "disabled",
+        "operational": False,
+        "degraded": False,
+        "ready": False,
+        "error": None,
+        "host": resolved.host,
+        "port": resolved.port,
+        "db": resolved.db,
+        "url": resolved.url,
+        "probe_deferred": True,
+    }
+
+
+def probe_foundation_redis_binding(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+    settings: FoundationRedisSettings | None = None,
+    capability_name: str = "foundation redis",
+) -> dict[str, Any]:
+    status = describe_foundation_redis_binding(project_dir=project_dir, settings=settings)
+    if not status["enabled"] or not status["configured"]:
+        status["probe_deferred"] = False
+        return status
+    try:
+        cache = get_required_foundation_cache(
+            project_dir=project_dir,
+            settings=settings,
+            capability_name=capability_name,
+        )
+        ready = bool(cache.ping())
+        status["ready"] = ready
+        status["operational"] = ready
+        status["degraded"] = not ready
+        status["probe_deferred"] = False
+        return status
+    except Exception as exc:
+        status["error"] = str(exc) or exc.__class__.__name__
+        status["degraded"] = True
+        status["probe_deferred"] = False
+        return status
+
+
+def reset_foundation_cache() -> None:
+    for cache in list(_CACHE_SINGLETONS.values()):
+        with contextlib.suppress(Exception):
+            cache.close()
+    _CACHE_SINGLETONS.clear()
+    _cached_required_foundation_redis_manager.cache_clear()
+
+
+def _cache_key(settings: FoundationRedisSettings) -> str:
+    return (
+        f"{settings.url or ''}|{settings.host}|{settings.port}|{settings.db}|"
+        f"{settings.connect_timeout_seconds}|{settings.socket_timeout_seconds}|"
+        f"{settings.operation_max_attempts}|{settings.connection_retry_attempts}|"
+        f"{settings.retry_base_delay_seconds}|{settings.retry_max_delay_seconds}|"
+        f"{settings.acquire_failure_cooldown_seconds}|{settings.health_failure_cooldown_seconds}"
+    )
+
+
+def _redis_snapshot(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+):
+    try:
+        return _payload_dict(_foundation_settings_section("cache", project_dir=project_dir))
+    except Exception:
+        return {}
+
+
+def _payload_dict(payload: Any) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        return dict(payload)
+    if hasattr(payload, "to_dict") and callable(payload.to_dict):
+        try:
+            value = payload.to_dict()
+        except Exception:
+            value = None
+        if isinstance(value, dict):
+            return dict(value)
+    return dict(getattr(payload, "__dict__", {}) or {})
+
+
+def _read_str(payload: Any, key: str) -> str:
+    if isinstance(payload, dict):
+        value = payload.get(key, "")
+    else:
+        value = getattr(payload, key, "")
+    return str(value or "").strip()
+
+
+def _read_optional_str(payload: Any, key: str) -> str | None:
+    value = _read_str(payload, key)
+    return value or None
+
+
+def _read_int(payload: Any, key: str, default: int) -> int:
+    if isinstance(payload, dict):
+        value = payload.get(key, default)
+    else:
+        value = getattr(payload, key, default)
+    try:
+        return int(value if value is not None else default)
+    except Exception:
+        return default
+
+
+def _read_float(payload: Any, key: str, default: float) -> float:
+    if isinstance(payload, dict):
+        value = payload.get(key, default)
+    else:
+        value = getattr(payload, key, default)
+    try:
+        return float(value if value is not None else default)
+    except Exception:
+        return default
+
+
+def _read_bool_value(payload: Any, key: str, default: bool) -> bool:
+    if isinstance(payload, dict):
+        value = payload.get(key, default)
+    else:
+        value = getattr(payload, key, default)
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+__all__ = [
+    "CacheService",
+    "describe_foundation_redis_binding",
+    "FoundationRedisUnavailable",
+    "FoundationRedisSettings",
+    "InMemoryFoundationCache",
+    "probe_foundation_redis_binding",
+    "RedisFoundationCache",
+    "SyncCacheService",
+    "SyncRedisAdapter",
+    "build_foundation_redis_config",
+    "build_required_foundation_redis_config",
+    "get_foundation_cache",
+    "get_required_foundation_cache",
+    "get_foundation_redis_manager",
+    "get_required_foundation_redis_connection",
+    "get_required_foundation_redis_manager",
+    "load_foundation_redis_settings",
+    "reset_foundation_cache",
+    "_LazyAccessor",
+]