Buckets:
| """ | |
| ACGS-2 Enhanced Agent Bus - Caching Utilities | |
| Constitutional Hash: 608508a9bd224290 | |
| High-performance caching layer for API responses and batch processing. | |
| """ | |
| import asyncio | |
| import hashlib | |
| import inspect | |
| import threading | |
| import time | |
| from collections import OrderedDict | |
| from collections.abc import Callable | |
| from functools import wraps | |
| from typing import TypeVar | |
| try: | |
| from enhanced_agent_bus._compat.constants import CONSTITUTIONAL_HASH | |
| except ImportError: | |
| CONSTITUTIONAL_HASH = "standalone" | |
| from enhanced_agent_bus.observability.structured_logging import get_logger | |
| # Import Redis exceptions for specific error handling | |
| try: | |
| from redis.exceptions import ConnectionError as RedisConnectionError | |
| from redis.exceptions import RedisError | |
| REDIS_EXCEPTIONS_AVAILABLE = True | |
| except ImportError: | |
| # Fallback if redis not installed | |
| RedisError = Exception # type: ignore[misc, assignment] | |
| RedisConnectionError = Exception # type: ignore[misc, assignment] | |
| REDIS_EXCEPTIONS_AVAILABLE = False | |
| logger = get_logger(__name__) | |
| T = TypeVar("T") | |
| DEFAULT_CACHE_HASH_MODE = "sha256" | |
| _CACHE_HASH_MODES = {"sha256", "fast"} | |
| CACHE_HASH_MODE = DEFAULT_CACHE_HASH_MODE | |
| try: | |
| from acgs2_perf import fast_hash | |
| FAST_HASH_AVAILABLE = True | |
| except ImportError: | |
| FAST_HASH_AVAILABLE = False | |
| # Thread-safe global cache with lock | |
| _local_cache: OrderedDict[str, tuple[object, float]] = OrderedDict() | |
| _cache_stats = {"hits": 0, "misses": 0, "evictions": 0} | |
| _cache_lock_sync = threading.Lock() # Protects _local_cache and _cache_stats (sync functions) | |
| _cache_lock_async = asyncio.Lock() # Protects _local_cache and _cache_stats (async functions) | |
| def _reset_cache_state() -> None: | |
| """Reset module-level cache state. Used by test fixtures.""" | |
| with _cache_lock_sync: | |
| _local_cache.clear() | |
| _cache_stats.update(hits=0, misses=0, evictions=0) | |
| def set_cache_hash_mode(mode: str) -> None: | |
| """Set cache hash mode for cache_key generation.""" | |
| if mode not in _CACHE_HASH_MODES: | |
| raise ValueError(f"Invalid cache hash mode: {mode}") | |
| global CACHE_HASH_MODE | |
| CACHE_HASH_MODE = mode | |
| if mode == "fast" and not FAST_HASH_AVAILABLE: | |
| logger.warning( | |
| "cache_hash_mode=fast requested but acgs2_perf.fast_hash unavailable; " | |
| "falling back to sha256" | |
| ) | |
| def cache_key(*args: object, **kwargs: object) -> str: | |
| key_data = f"{args}:{sorted(kwargs.items())}" | |
| if CACHE_HASH_MODE == "fast" and FAST_HASH_AVAILABLE: | |
| return f"fast:{fast_hash(key_data):016x}" | |
| return hashlib.sha256(key_data.encode()).hexdigest()[:16] | |
| def _make_cache_key(func_name: str, args: tuple[object, ...], kwargs: dict[str, object]) -> str: | |
| """Build deterministic cache key for a function invocation.""" | |
| return f"{func_name}:{cache_key(*args, **kwargs)}" | |
| async def _async_lookup_cache(key: str, now: float) -> tuple[bool, object | None]: | |
| """Lookup cache value under async lock.""" | |
| async with _cache_lock_async: | |
| cached_entry = _local_cache.get(key) | |
| if cached_entry is None: | |
| return False, None | |
| value, expires = cached_entry | |
| if now < expires: | |
| _cache_stats["hits"] += 1 | |
| _local_cache.move_to_end(key) | |
| return True, value | |
| _local_cache.pop(key, None) | |
| return False, None | |
| def _sync_lookup_cache(key: str, now: float) -> tuple[bool, object | None]: | |
| """Lookup cache value under thread lock.""" | |
| with _cache_lock_sync: | |
| cached_entry = _local_cache.get(key) | |
| if cached_entry is None: | |
| return False, None | |
| value, expires = cached_entry | |
| if now < expires: | |
| _cache_stats["hits"] += 1 | |
| _local_cache.move_to_end(key) | |
| return True, value | |
| _local_cache.pop(key, None) | |
| return False, None | |
| async def _async_store_cache(key: str, value: object, expires_at: float, max_size: int) -> None: | |
| """Store cache value under async lock with eviction.""" | |
| async with _cache_lock_async: | |
| if len(_local_cache) >= max_size: | |
| _local_cache.popitem(last=False) | |
| _cache_stats["evictions"] += 1 | |
| _local_cache[key] = (value, expires_at) | |
| def _sync_store_cache(key: str, value: object, expires_at: float, max_size: int) -> None: | |
| """Store cache value under thread lock with eviction.""" | |
| with _cache_lock_sync: | |
| if len(_local_cache) >= max_size: | |
| _local_cache.popitem(last=False) | |
| _cache_stats["evictions"] += 1 | |
| _local_cache[key] = (value, expires_at) | |
| def _record_cache_miss() -> None: | |
| """Increment cache miss counter in a lock-safe way.""" | |
| with _cache_lock_sync: | |
| _cache_stats["misses"] += 1 | |
| def cached(ttl_seconds: float = 300.0, max_size: int = 1000): | |
| def decorator(func: Callable[..., T]) -> Callable[..., T]: | |
| async def async_wrapper(*args: object, **kwargs: object) -> T: | |
| key = _make_cache_key(func.__name__, args, kwargs) | |
| now = time.time() | |
| hit, cached_value = await _async_lookup_cache(key, now) | |
| if hit: | |
| return cached_value # type: ignore[return-value] | |
| _record_cache_miss() | |
| result = await func(*args, **kwargs) # type: ignore[misc] | |
| await _async_store_cache(key, result, now + ttl_seconds, max_size) | |
| return result # type: ignore[no-any-return] | |
| def sync_wrapper(*args: object, **kwargs: object) -> T: | |
| key = _make_cache_key(func.__name__, args, kwargs) | |
| now = time.time() | |
| hit, cached_value = _sync_lookup_cache(key, now) | |
| if hit: | |
| return cached_value # type: ignore[return-value] | |
| _record_cache_miss() | |
| result = func(*args, **kwargs) | |
| _sync_store_cache(key, result, now + ttl_seconds, max_size) | |
| return result | |
| if inspect.iscoroutinefunction(func): | |
| return async_wrapper # type: ignore[return-value] | |
| return sync_wrapper | |
| return decorator | |
| def get_cache_stats() -> dict[str, int]: | |
| """Get cache statistics (thread-safe).""" | |
| with _cache_lock_sync: | |
| return _cache_stats.copy() | |
| def clear_cache() -> int: | |
| """Clear all cache entries (thread-safe).""" | |
| with _cache_lock_sync: | |
| count = len(_local_cache) | |
| _local_cache.clear() | |
| return count | |
| def invalidate_pattern(pattern: str) -> int: | |
| """Invalidate cache entries matching pattern (thread-safe).""" | |
| with _cache_lock_sync: | |
| keys_to_delete = [k for k in _local_cache if pattern in k] | |
| for key in keys_to_delete: | |
| del _local_cache[key] | |
| return len(keys_to_delete) | |
| class RedisCacheClient: | |
| """Redis cache client with graceful error handling. | |
| Uses specific Redis exceptions for targeted error handling while | |
| maintaining fail-safe behavior for cache operations. | |
| """ | |
| def __init__(self, redis_pool: object): | |
| self._pool = redis_pool | |
| self._prefix = "acgs2:cache:" | |
| async def get(self, key: str) -> str | None: | |
| """Get value from cache, returns None on any Redis error.""" | |
| try: | |
| async with self._pool.connection() as conn: | |
| result = await conn.get(f"{self._prefix}{key}") | |
| return str(result) if result is not None else None | |
| except RedisConnectionError: | |
| logger.debug(f"[{CONSTITUTIONAL_HASH}] Redis connection error on cache get") | |
| return None | |
| except RedisError as e: | |
| logger.warning(f"[{CONSTITUTIONAL_HASH}] Redis error on cache get: {e}") | |
| return None | |
| async def set(self, key: str, value: str, ttl: int = 300) -> bool: | |
| """Set value in cache, returns False on any Redis error.""" | |
| try: | |
| async with self._pool.connection() as conn: | |
| await conn.setex(f"{self._prefix}{key}", ttl, value) | |
| return True | |
| except RedisConnectionError: | |
| logger.debug(f"[{CONSTITUTIONAL_HASH}] Redis connection error on cache set") | |
| return False | |
| except RedisError as e: | |
| logger.warning(f"[{CONSTITUTIONAL_HASH}] Redis error on cache set: {e}") | |
| return False | |
| async def delete(self, key: str) -> bool: | |
| """Delete key from cache, returns False on any Redis error.""" | |
| try: | |
| async with self._pool.connection() as conn: | |
| await conn.delete(f"{self._prefix}{key}") | |
| return True | |
| except RedisConnectionError: | |
| logger.debug(f"[{CONSTITUTIONAL_HASH}] Redis connection error on cache delete") | |
| return False | |
| except RedisError as e: | |
| logger.warning(f"[{CONSTITUTIONAL_HASH}] Redis error on cache delete: {e}") | |
| return False | |
| async def mget(self, keys: list[str]) -> list[str | None]: | |
| """Get multiple values from cache, returns list of None on any Redis error.""" | |
| try: | |
| async with self._pool.connection() as conn: | |
| prefixed = [f"{self._prefix}{k}" for k in keys] | |
| return list(await conn.mget(prefixed)) # type: ignore[arg-type] | |
| except RedisConnectionError: | |
| logger.debug(f"[{CONSTITUTIONAL_HASH}] Redis connection error on cache mget") | |
| return [None] * len(keys) | |
| except RedisError as e: | |
| logger.warning(f"[{CONSTITUTIONAL_HASH}] Redis error on cache mget: {e}") | |
| return [None] * len(keys) | |
Xet Storage Details
- Size:
- 9.57 kB
- Xet hash:
- f361c639091bbc9724e88810cd6504d7c7d1365d4003bd9fb62af17dbfcd1776
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.