aury-boot 0.0.37__tar.gz → 0.0.38__tar.gz

{aury_boot-0.0.37 → aury_boot-0.0.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.37
+Version: 0.0.38
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.37 → aury_boot-0.0.38}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.37'
-__version_tuple__ = version_tuple = (0, 0, 37)
+__version__ = version = '0.0.38'
+__version_tuple__ = version_tuple = (0, 0, 38)
 
 __commit_id__ = commit_id = None

aury_boot-0.0.38/aury/boot/infrastructure/cache/backends.py

@@ -0,0 +1,14 @@
+"""缓存后端实现（兼容层）。
+
+实际实现在 redis.py 和 memory.py 中。
+"""
+
+from .memory import MemcachedCache, MemoryCache
+from .redis import RedisCache
+
+__all__ = [
+    "MemcachedCache",
+    "MemoryCache",
+    "RedisCache",
+]
+

{aury_boot-0.0.37 → aury_boot-0.0.38}/aury/boot/infrastructure/cache/base.py

@@ -71,6 +71,44 @@ class ICache(ABC):
     async def close(self) -> None:
         """关闭连接。"""
         pass
+    
+    # ==================== 分布式锁 ====================
+    
+    @abstractmethod
+    async def acquire_lock(
+        self,
+        key: str,
+        token: str,
+        timeout: int,
+        blocking: bool,
+        blocking_timeout: float | None,
+    ) -> bool:
+        """获取分布式锁。
+        
+        Args:
+            key: 锁的键名（已加 lock: 前缀）
+            token: 锁的 token
+            timeout: 锁的超时时间（秒）
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Returns:
+            bool: 是否获取成功
+        """
+        pass
+    
+    @abstractmethod
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放分布式锁。
+        
+        Args:
+            key: 锁的键名（已加 lock: 前缀）
+            token: 获取锁时的 token
+            
+        Returns:
+            bool: 是否成功释放
+        """
+        pass
 
 
 __all__ = [

{aury_boot-0.0.37 → aury_boot-0.0.38}/aury/boot/infrastructure/cache/manager.py

@@ -5,11 +5,15 @@
 
 from __future__ import annotations
 
+import asyncio
 from collections.abc import Callable
+from contextlib import asynccontextmanager
 from datetime import timedelta
 from functools import wraps
 import hashlib
-from typing import Any, TypeVar
+import time
+from typing import Any, AsyncIterator, TypeVar
+import uuid
 
 from aury.boot.common.logging import logger
 
@@ -328,6 +332,152 @@ class CacheManager:
             self._backend = None
             logger.info("缓存管理器已清理")
     
+    # ==================== 分布式锁 ====================
+    
+    async def acquire_lock(
+        self,
+        key: str,
+        *,
+        timeout: int = 30,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> str | None:
+        """获取分布式锁。
+        
+        Args:
+            key: 锁的键名
+            timeout: 锁的超时时间（秒），防止死锁
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Returns:
+            str | None: 锁的 token（用于释放），获取失败返回 None
+        """
+        lock_key = f"lock:{key}"
+        token = str(uuid.uuid4())
+        
+        acquired = await self.backend.acquire_lock(
+            lock_key, token, timeout, blocking, blocking_timeout
+        )
+        return token if acquired else None
+    
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放分布式锁。
+        
+        Args:
+            key: 锁的键名
+            token: acquire_lock 返回的 token
+            
+        Returns:
+            bool: 是否成功释放
+        """
+        lock_key = f"lock:{key}"
+        return await self.backend.release_lock(lock_key, token)
+    
+    @asynccontextmanager
+    async def lock(
+        self,
+        key: str,
+        *,
+        timeout: int = 30,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> AsyncIterator[bool]:
+        """分布式锁上下文管理器。
+        
+        Args:
+            key: 锁的键名
+            timeout: 锁的超时时间（秒）
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Yields:
+            bool: 是否成功获取锁
+            
+        示例:
+            async with cache.lock("my_resource") as acquired:
+                if acquired:
+                    # 执行需要互斥的操作
+                    pass
+        """
+        token = await self.acquire_lock(
+            key,
+            timeout=timeout,
+            blocking=blocking,
+            blocking_timeout=blocking_timeout,
+        )
+        try:
+            yield token is not None
+        finally:
+            if token:
+                await self.release_lock(key, token)
+    
+    @asynccontextmanager
+    async def semaphore(
+        self,
+        key: str,
+        max_concurrency: int,
+        *,
+        timeout: int = 300,
+        blocking: bool = True,
+        blocking_timeout: float | None = None,
+    ) -> AsyncIterator[bool]:
+        """分布式信号量（限制并发数）。
+        
+        Args:
+            key: 信号量的键名
+            max_concurrency: 最大并发数
+            timeout: 单个槽位的超时时间（秒）
+            blocking: 是否阻塞等待
+            blocking_timeout: 阻塞等待的最大时间（秒）
+            
+        Yields:
+            bool: 是否成功获取槽位
+            
+        示例:
+            async with cache.semaphore("pdf_ocr", max_concurrency=2) as acquired:
+                if acquired:
+                    # 执行受并发限制的操作
+                    pass
+        """
+        slot_token: str | None = None
+        acquired_slot: int | None = None
+        start_time = time.monotonic()
+        
+        try:
+            while True:
+                # 尝试获取任意一个槽位
+                for slot in range(max_concurrency):
+                    slot_key = f"{key}:slot:{slot}"
+                    token = await self.acquire_lock(
+                        slot_key,
+                        timeout=timeout,
+                        blocking=False,
+                    )
+                    if token:
+                        slot_token = token
+                        acquired_slot = slot
+                        yield True
+                        return
+                
+                if not blocking:
+                    yield False
+                    return
+                
+                # 检查是否超时
+                if blocking_timeout is not None:
+                    elapsed = time.monotonic() - start_time
+                    if elapsed >= blocking_timeout:
+                        yield False
+                        return
+                
+                # 等待后重试
+                await asyncio.sleep(0.1)
+        finally:
+            if slot_token and acquired_slot is not None:
+                slot_key = f"{key}:slot:{acquired_slot}"
+                await self.release_lock(slot_key, slot_token)
+    
     def __repr__(self) -> str:
         """字符串表示。"""
         backend_name = self.backend_type if self._backend else "未初始化"

aury_boot-0.0.37/aury/boot/infrastructure/cache/backends.py → aury_boot-0.0.38/aury/boot/infrastructure/cache/memory.py

@@ -1,208 +1,18 @@
-"""缓存后端实现。
-
-提供 Redis、Memory、Memcached 等缓存后端的实现。
-"""
+"""内存和 Memcached 缓存后端实现。"""
 
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable
-from datetime import timedelta
+import fnmatch
 import json
-import pickle
-from typing import TYPE_CHECKING, Any
-
-from redis.asyncio import Redis
+import time
+from datetime import timedelta
+from typing import Any
 
 from aury.boot.common.logging import logger
 
 from .base import ICache
 
-if TYPE_CHECKING:
-    from aury.boot.infrastructure.clients.redis import RedisClient
-
-
-class RedisCache(ICache):
-    """Redis缓存实现。
-    
-    支持两种初始化方式：
-    1. 传入 URL 自行创建连接
-    2. 传入 RedisClient 实例（推荐）
-    """
-    
-    def __init__(
-        self,
-        url: str | None = None,
-        *,
-        redis_client: RedisClient | None = None,
-        serializer: str = "json",
-    ):
-        """初始化Redis缓存。
-        
-        Args:
-            url: Redis连接URL
-            redis_client: RedisClient 实例（推荐）
-            serializer: 序列化方式（json/pickle）
-        """
-        self._url = url
-        self._redis_client = redis_client
-        self._serializer = serializer
-        self._redis: Redis | None = None
-        self._owns_connection = False  # 是否自己拥有连接（需要自己关闭）
-    
-    async def initialize(self) -> None:
-        """初始化连接。"""
-        # 优先使用 RedisClient
-        if self._redis_client is not None:
-            self._redis = self._redis_client.connection
-            self._owns_connection = False
-            logger.info("Redis缓存初始化成功（使用 RedisClient）")
-            return
-        
-        # 使用 URL 创建连接
-        if self._url:
-            try:
-                self._redis = Redis.from_url(
-                    self._url,
-                    encoding="utf-8",
-                    decode_responses=False,
-                    socket_connect_timeout=5,
-                    socket_timeout=5,
-                )
-                await self._redis.ping()
-                self._owns_connection = True
-                logger.info("Redis缓存初始化成功")
-            except Exception as exc:
-                logger.error(f"Redis连接失败: {exc}")
-                raise
-        else:
-            raise ValueError("Redis缓存需要提供 url 或 redis_client 参数")
-    
-    async def get(self, key: str, default: Any = None) -> Any:
-        """获取缓存。"""
-        if not self._redis:
-            return default
-        
-        try:
-            data = await self._redis.get(key)
-            if data is None:
-                return default
-            
-            # 使用函数式编程处理序列化器
-            deserializers: dict[str, Callable[[bytes], Any]] = {
-                "json": lambda d: json.loads(d.decode()),
-                "pickle": pickle.loads,
-            }
-            
-            deserializer = deserializers.get(self._serializer)
-            if deserializer:
-                return deserializer(data)
-            return data.decode()
-        except Exception as exc:
-            logger.error(f"Redis获取失败: {key}, {exc}")
-            return default
-    
-    async def set(
-        self,
-        key: str,
-        value: Any,
-        expire: int | timedelta | None = None,
-    ) -> bool:
-        """设置缓存。"""
-        if not self._redis:
-            return False
-        
-        try:
-            # 使用函数式编程处理序列化器
-            serializers: dict[str, Callable[[Any], bytes]] = {
-                "json": lambda v: json.dumps(v).encode(),
-                "pickle": pickle.dumps,
-            }
-            
-            serializer = serializers.get(self._serializer)
-            if serializer:
-                data = serializer(value)
-            else:
-                data = str(value).encode()
-            
-            # 转换过期时间
-            if isinstance(expire, timedelta):
-                expire = int(expire.total_seconds())
-            
-            await self._redis.set(key, data, ex=expire)
-            return True
-        except Exception as exc:
-            logger.error(f"Redis设置失败: {key}, {exc}")
-            return False
-    
-    async def delete(self, *keys: str) -> int:
-        """删除缓存。"""
-        if not self._redis or not keys:
-            return 0
-        
-        try:
-            return await self._redis.delete(*keys)
-        except Exception as exc:
-            logger.error(f"Redis删除失败: {keys}, {exc}")
-            return 0
-    
-    async def exists(self, *keys: str) -> int:
-        """检查缓存是否存在。"""
-        if not self._redis or not keys:
-            return 0
-        
-        try:
-            return await self._redis.exists(*keys)
-        except Exception as exc:
-            logger.error(f"Redis检查失败: {keys}, {exc}")
-            return 0
-    
-    async def clear(self) -> None:
-        """清空所有缓存。"""
-        if self._redis:
-            await self._redis.flushdb()
-            logger.info("Redis缓存已清空")
-    
-    async def delete_pattern(self, pattern: str) -> int:
-        """按模式删除缓存。
-        
-        Args:
-            pattern: 通配符模式，如 "todo:*"
-            
-        Returns:
-            int: 删除的键数量
-        """
-        if not self._redis:
-            return 0
-        
-        try:
-            # 使用 SCAN 遍历匹配的键（比 KEYS 更安全，不会阻塞）
-            count = 0
-            cursor = 0
-            while True:
-                cursor, keys = await self._redis.scan(cursor, match=pattern, count=100)
-                if keys:
-                    count += await self._redis.delete(*keys)
-                if cursor == 0:
-                    break
-            logger.debug(f"按模式删除缓存: {pattern}, 删除 {count} 个键")
-            return count
-        except Exception as exc:
-            logger.error(f"Redis模式删除失败: {pattern}, {exc}")
-            return 0
-    
-    async def close(self) -> None:
-        """关闭连接（仅当自己拥有连接时）。"""
-        if self._redis and self._owns_connection:
-            await self._redis.close()
-            logger.info("Redis连接已关闭")
-        self._redis = None
-    
-    @property
-    def redis(self) -> Redis | None:
-        """获取Redis客户端。"""
-        return self._redis
-
 
 class MemoryCache(ICache):
     """内存缓存实现。"""
@@ -295,8 +105,6 @@ class MemoryCache(ICache):
         Returns:
             int: 删除的键数量
         """
-        import fnmatch
-        
         async with self._lock:
             keys_to_delete = [
                 key for key in self._cache
@@ -314,6 +122,60 @@ class MemoryCache(ICache):
     async def size(self) -> int:
         """获取缓存大小。"""
         return len(self._cache)
+    
+    # ==================== 内存锁 ====================
+    
+    async def acquire_lock(
+        self,
+        key: str,
+        token: str,
+        timeout: int,
+        blocking: bool,
+        blocking_timeout: float | None,
+    ) -> bool:
+        """获取内存锁（单进程）。"""
+        start_time = time.monotonic()
+        
+        while True:
+            async with self._lock:
+                # 检查锁是否存在
+                if key not in self._cache:
+                    # 设置锁
+                    expire_at = asyncio.get_event_loop().time() + timeout
+                    self._cache[key] = (token, expire_at)
+                    return True
+                
+                # 检查锁是否过期
+                existing_token, expire_at = self._cache[key]
+                if expire_at is not None and asyncio.get_event_loop().time() > expire_at:
+                    # 锁已过期，重新获取
+                    new_expire_at = asyncio.get_event_loop().time() + timeout
+                    self._cache[key] = (token, new_expire_at)
+                    return True
+            
+            if not blocking:
+                return False
+            
+            # 检查是否超时
+            if blocking_timeout is not None:
+                elapsed = time.monotonic() - start_time
+                if elapsed >= blocking_timeout:
+                    return False
+            
+            # 短暂等待后重试
+            await asyncio.sleep(0.05)
+    
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放内存锁。"""
+        async with self._lock:
+            if key not in self._cache:
+                return False
+            
+            existing_token, _ = self._cache[key]
+            if existing_token == token:
+                del self._cache[key]
+                return True
+            return False
 
 
 class MemcachedCache(ICache):
@@ -323,7 +185,7 @@ class MemcachedCache(ICache):
         """初始化Memcached缓存。
         
         Args:
-            servers: Memcached服务器列表，如 ["127.0.0.1:11211"]
+            servers: Memcached服务器列表，如 ["*********:11211"]
         """
         self._servers = servers
         self._client = None
@@ -422,11 +284,23 @@ class MemcachedCache(ICache):
         if self._client:
             self._client.close()
             logger.info("Memcached连接已关闭")
+    
+    # Memcached 不支持分布式锁
+    async def acquire_lock(
+        self,
+        key: str,
+        token: str,
+        timeout: int,
+        blocking: bool,
+        blocking_timeout: float | None,
+    ) -> bool:
+        """获取锁（Memcached 不支持）。"""
+        logger.warning("Memcached 不支持分布式锁，请使用 Redis 或 Memory 后端")
+        return False
+    
+    async def release_lock(self, key: str, token: str) -> bool:
+        """释放锁（Memcached 不支持）。"""
+        return False
 
 
-__all__ = [
-    "MemcachedCache",
-    "MemoryCache",
-    "RedisCache",
-]
-
+__all__ = ["MemcachedCache", "MemoryCache"]