aury-boot 0.0.40__tar.gz → 0.0.41__tar.gz

{aury_boot-0.0.40 → aury_boot-0.0.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.40
+Version: 0.0.41
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: aiohttp>=3.11.0
@@ -28,6 +28,7 @@ Requires-Dist: aiosqlite>=0.21.0; extra == 'all'
 Requires-Dist: apscheduler>=3.11.1; extra == 'all'
 Requires-Dist: asyncpg>=0.31.0; extra == 'all'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'all'
+Requires-Dist: coredis>=5.6.0; extra == 'all'
 Requires-Dist: dramatiq>=1.18.0; extra == 'all'
 Requires-Dist: pika>=1.3.2; extra == 'all'
 Requires-Dist: psutil>=7.0.0; extra == 'all'
@@ -35,6 +36,8 @@ Requires-Dist: pyroscope-io>=0.8.7; extra == 'all'
 Requires-Dist: redis>=7.1.0; extra == 'all'
 Provides-Extra: broadcaster
 Requires-Dist: broadcaster[redis]>=0.3.1; extra == 'broadcaster'
+Provides-Extra: channel-cluster
+Requires-Dist: coredis>=5.6.0; extra == 'channel-cluster'
 Provides-Extra: dev
 Requires-Dist: httpx>=0.28.1; extra == 'dev'
 Requires-Dist: mypy>=1.19.0; extra == 'dev'
@@ -68,6 +71,7 @@ Requires-Dist: aiosqlite>=0.21.0; extra == 'recommended'
 Requires-Dist: apscheduler>=3.11.1; extra == 'recommended'
 Requires-Dist: asyncpg>=0.31.0; extra == 'recommended'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'recommended'
+Requires-Dist: coredis>=5.6.0; extra == 'recommended'
 Requires-Dist: dramatiq>=1.18.0; extra == 'recommended'
 Requires-Dist: opentelemetry-api>=1.25.0; extra == 'recommended'
 Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.46b0; extra == 'recommended'

{aury_boot-0.0.40 → aury_boot-0.0.41}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.40'
-__version_tuple__ = version_tuple = (0, 0, 40)
+__version__ = version = '0.0.41'
+__version_tuple__ = version_tuple = (0, 0, 41)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.40 → aury_boot-0.0.41}/aury/boot/application/app/components.py

@@ -318,7 +318,18 @@ class SchedulerComponent(Component):
         # jobstores: 根据 URL 自动选择存储后端
         if scheduler_config.jobstore_url:
             url = scheduler_config.jobstore_url
-            if url.startswith("redis://"):
+            if url.startswith("redis-cluster://"):
+                # Redis Cluster 模式
+                try:
+                    from aury.boot.infrastructure.scheduler.jobstores import RedisClusterJobStore
+                    
+                    scheduler_kwargs["jobstores"] = {
+                        "default": RedisClusterJobStore(url=url)
+                    }
+                    logger.info(f"调度器使用 Redis Cluster 存储: {url.split('@')[-1].split('/')[0]}")
+                except ImportError:
+                    logger.warning("Redis Cluster jobstore 需要安装 redis[cluster]: pip install 'redis[cluster]'")
+            elif url.startswith("redis://"):
                 try:
                     from urllib.parse import urlparse
                     from apscheduler.jobstores.redis import RedisJobStore

{aury_boot-0.0.40 → aury_boot-0.0.41}/aury/boot/application/config/settings.py

@@ -263,15 +263,19 @@ class ChannelSettings(BaseModel):
     支持的后端类型：
     - memory: 内存后端（默认，单进程）
     - redis: Redis Pub/Sub（多进程/分布式）
+    - redis_cluster: Redis Cluster Sharded Pub/Sub（Redis 7.0+）
+    
+    注意：URL 的 scheme 会自动决定后端类型：
+    - redis-cluster://... 自动使用 redis_cluster 后端
     """
     
     backend: str = Field(
         default="",
-        description="通道后端 (memory/redis)，空字符串表示不启用"
+        description="通道后端 (memory/redis/redis_cluster)，空字符串表示不启用"
     )
     url: str | None = Field(
         default=None,
-        description="Redis URL（当 backend=redis 时需要）"
+        description="连接 URL（redis://... 或 redis-cluster://...）"
     )
 
 
@@ -472,6 +476,7 @@ class SchedulerSettings(BaseModel):
         default=None,
         description=(
             "任务存储 URL。支持：\n"
+            "- redis-cluster://password@host:port（Redis Cluster 存储）\n"
             "- redis://localhost:6379/0（Redis 存储）\n"
             "- sqlite:///jobs.db（SQLite 存储）\n"
             "- postgresql://user:pass@host/db（PostgreSQL 存储）\n"

{aury_boot-0.0.40 → aury_boot-0.0.41}/aury/boot/infrastructure/cache/redis.py

@@ -1,4 +1,9 @@
-"""Redis 缓存后端实现。"""
+"""Redis 缓存后端实现。
+
+支持普通 Redis 和 Redis Cluster：
+- redis://... - 普通 Redis
+- redis-cluster://... - Redis Cluster
+"""
 
 from __future__ import annotations
 
@@ -9,6 +14,7 @@ import time
 from collections.abc import Callable
 from datetime import timedelta
 from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
 
 from redis.asyncio import Redis
 
@@ -17,6 +23,7 @@ from aury.boot.common.logging import logger
 from .base import ICache
 
 if TYPE_CHECKING:
+    from redis.asyncio.cluster import RedisCluster
     from aury.boot.infrastructure.clients.redis import RedisClient
 
 
@@ -24,7 +31,7 @@ class RedisCache(ICache):
     """Redis缓存实现。
     
     支持两种初始化方式：
-    1. 传入 URL 自行创建连接
+    1. 传入 URL 自行创建连接（支持 redis:// 和 redis-cluster://）
     2. 传入 RedisClient 实例（推荐）
     """
     
@@ -38,44 +45,95 @@ class RedisCache(ICache):
         """初始化Redis缓存。
         
         Args:
-            url: Redis连接URL
+            url: Redis连接URL（支持 redis:// 和 redis-cluster://）
             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  # 是否自己拥有连接（需要自己关闭）
+        self._redis: Redis | RedisCluster | None = None
+        self._owns_connection = False
+        self._is_cluster = False
     
     async def initialize(self) -> None:
         """初始化连接。"""
         # 优先使用 RedisClient
         if self._redis_client is not None:
             self._redis = self._redis_client.connection
+            self._is_cluster = getattr(self._redis_client, "is_cluster", False)
             self._owns_connection = False
-            logger.info("Redis缓存初始化成功（使用 RedisClient）")
+            mode = "Cluster" if self._is_cluster else "Standalone"
+            logger.info(f"Redis缓存初始化成功（使用 RedisClient, {mode}）")
             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,
-                )
+                if self._url.startswith("redis-cluster://"):
+                    await self._init_cluster()
+                else:
+                    await self._init_standalone()
                 await self._redis.ping()
                 self._owns_connection = True
-                logger.info("Redis缓存初始化成功")
+                mode = "Cluster" if self._is_cluster else "Standalone"
+                logger.info(f"Redis缓存初始化成功 ({mode})")
             except Exception as exc:
                 logger.error(f"Redis连接失败: {exc}")
                 raise
         else:
             raise ValueError("Redis缓存需要提供 url 或 redis_client 参数")
     
+    async def _init_standalone(self) -> None:
+        """初始化普通 Redis。"""
+        self._redis = Redis.from_url(
+            self._url,
+            encoding="utf-8",
+            decode_responses=False,
+            socket_connect_timeout=5,
+            socket_timeout=5,
+        )
+        self._is_cluster = False
+    
+    async def _init_cluster(self) -> None:
+        """初始化 Redis Cluster。
+        
+        支持 URL 格式:
+        - redis-cluster://password@host:port （密码在用户名位置）
+        - redis-cluster://:password@host:port （标准格式）
+        - redis-cluster://username:password@host:port （ACL 模式）
+        """
+        from redis.asyncio.cluster import RedisCluster
+        
+        parsed_url = self._url.replace("redis-cluster://", "redis://")
+        parsed = urlparse(parsed_url)
+        
+        # 提取认证信息
+        username = parsed.username
+        password = parsed.password
+        
+        # 处理 password@host 格式（密码在用户名位置）
+        if username and not password:
+            password = username
+            username = None
+        
+        # 构建连接参数
+        cluster_kwargs: dict = {
+            "host": parsed.hostname or "localhost",
+            "port": parsed.port or 6379,
+            "decode_responses": False,
+            "socket_connect_timeout": 5,
+            "socket_timeout": 5,
+        }
+        
+        if username:
+            cluster_kwargs["username"] = username
+        if password:
+            cluster_kwargs["password"] = password
+        
+        self._redis = RedisCluster(**cluster_kwargs)
+        self._is_cluster = True
+    
     async def get(self, key: str, default: Any = None) -> Any:
         """获取缓存。"""
         if not self._redis:
@@ -192,15 +250,23 @@ class RedisCache(ICache):
     async def close(self) -> None:
         """关闭连接（仅当自己拥有连接时）。"""
         if self._redis and self._owns_connection:
-            await self._redis.close()
+            if self._is_cluster:
+                await self._redis.aclose()
+            else:
+                await self._redis.close()
             logger.info("Redis连接已关闭")
         self._redis = None
     
     @property
-    def redis(self) -> Redis | None:
+    def redis(self) -> Redis | RedisCluster | None:
         """获取Redis客户端。"""
         return self._redis
     
+    @property
+    def is_cluster(self) -> bool:
+        """检查是否为集群模式。"""
+        return self._is_cluster
+    
     # ==================== 分布式锁 ====================
     # TODO: 后续优化考虑：
     #   - 看门狗（Watchdog）机制：自动续期，防止业务执行超过锁超时导致提前释放

{aury_boot-0.0.40 → aury_boot-0.0.41}/aury/boot/infrastructure/channel/__init__.py

@@ -9,7 +9,7 @@
 - postgres:// - PostgreSQL LISTEN/NOTIFY
 """
 
-from .backends import BroadcasterChannel
+from .backends import BroadcasterChannel, RedisClusterChannel
 from .base import ChannelBackend, ChannelMessage, IChannel
 from .manager import ChannelManager
 
@@ -22,4 +22,5 @@ __all__ = [
     "ChannelManager",
     # 后端实现
     "BroadcasterChannel",
+    "RedisClusterChannel",
 ]

aury_boot-0.0.41/aury/boot/infrastructure/channel/backends/__init__.py

@@ -0,0 +1,6 @@
+"""通道后端实现。"""
+
+from .broadcaster import BroadcasterChannel
+from .redis_cluster_channel import RedisClusterChannel
+
+__all__ = ["BroadcasterChannel", "RedisClusterChannel"]

aury_boot-0.0.41/aury/boot/infrastructure/channel/backends/redis_cluster.py

@@ -0,0 +1,124 @@
+"""Redis Cluster 通道后端。
+
+使用 coredis 库支持异步 Redis Cluster Sharded Pub/Sub (Redis 7.0+)。
+
+URL 格式：
+    redis-cluster://password@host:port
+    redis-cluster://host:port
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+from aury.boot.common.logging import logger
+
+try:
+    from coredis import RedisCluster
+except ImportError as exc:
+    raise ImportError(
+        "Redis Cluster Channel 需要安装 coredis: pip install coredis"
+    ) from exc
+
+
+@dataclass
+class Event:
+    """与 broadcaster._base.Event 兼容的事件类。"""
+    channel: str
+    message: str
+
+
+class RedisClusterBackend:
+    """Redis Cluster Pub/Sub 后端。
+    
+    使用 coredis 库的 sharded_pubsub() 支持 Sharded Pub/Sub。
+    与 broadcaster.RedisBackend 接口兼容。
+    """
+
+    def __init__(self, url: str) -> None:
+        host, port, password = self._parse_url(url)
+        
+        self._client: RedisCluster = RedisCluster(
+            host=host,
+            port=port,
+            password=password,
+            decode_responses=True,
+        )
+        self._pubsub: Any = None
+        self._queue: asyncio.Queue[Event] = asyncio.Queue()
+        self._listener_task: asyncio.Task | None = None
+        self._subscribed_channels: set[str] = set()
+
+    def _parse_url(self, url: str) -> tuple[str, int, str | None]:
+        """解析 URL。"""
+        url = url.replace("redis-cluster://", "redis://")
+        parsed = urlparse(url)
+        password = parsed.password
+        # 支持 password@host 格式
+        if not password and parsed.username:
+            password = parsed.username
+        return parsed.hostname or "localhost", parsed.port or 6379, password
+
+    async def connect(self) -> None:
+        """连接并初始化 pubsub。"""
+        # coredis 的 sharded_pubsub() 支持 Redis 7.0+ Sharded Pub/Sub
+        self._pubsub = self._client.sharded_pubsub()
+        self._listener_task = asyncio.create_task(self._listen_loop())
+        logger.debug("Redis Cluster Channel 已连接")
+
+    async def disconnect(self) -> None:
+        """断开连接。"""
+        if self._listener_task:
+            self._listener_task.cancel()
+            try:
+                await self._listener_task
+            except asyncio.CancelledError:
+                pass
+        if self._pubsub:
+            await self._pubsub.sunsubscribe()
+        await self._client.close()
+        logger.debug("Redis Cluster Channel 已断开")
+
+    async def subscribe(self, channel: str) -> None:
+        """订阅频道。"""
+        if self._pubsub:
+            await self._pubsub.ssubscribe(channel)
+            self._subscribed_channels.add(channel)
+
+    async def unsubscribe(self, channel: str) -> None:
+        """取消订阅。"""
+        if self._pubsub and channel in self._subscribed_channels:
+            await self._pubsub.sunsubscribe(channel)
+            self._subscribed_channels.discard(channel)
+
+    async def publish(self, channel: str, message: str) -> None:
+        """发布消息（使用 SPUBLISH）。"""
+        await self._client.spublish(channel, message)
+
+    async def next_published(self) -> Event:
+        """获取下一条消息。"""
+        return await self._queue.get()
+
+    async def _listen_loop(self) -> None:
+        """监听消息循环。"""
+        while True:
+            try:
+                if self._pubsub:
+                    async for message in self._pubsub:
+                        if message and message.get("type") in ("message", "smessage"):
+                            event = Event(
+                                channel=message.get("channel", ""),
+                                message=message.get("data", ""),
+                            )
+                            await self._queue.put(event)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.warning(f"Redis Cluster pubsub error: {e}")
+                await asyncio.sleep(1)
+
+
+__all__ = ["RedisClusterBackend"]

aury_boot-0.0.41/aury/boot/infrastructure/channel/backends/redis_cluster_channel.py

@@ -0,0 +1,139 @@
+"""Redis Cluster 通道封装。
+
+使用 RedisClusterBackend，提供与 BroadcasterChannel 一致的接口。
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from datetime import datetime
+
+from aury.boot.common.logging import logger
+
+from ..base import ChannelMessage, IChannel
+from .redis_cluster import RedisClusterBackend
+
+
+class RedisClusterChannel(IChannel):
+    """Redis Cluster 通道实现。
+    
+    使用 broadcaster 架构：共享连接 + Queue 分发。
+    支持 Sharded Pub/Sub (Redis 7.0+)。
+    """
+
+    def __init__(self, url: str) -> None:
+        """初始化 Redis Cluster 通道。
+
+        Args:
+            url: redis-cluster://[password@]host:port
+        """
+        self._url = url
+        self._backend = RedisClusterBackend(url)
+        self._connected = False
+        # 订阅者管理（与 broadcaster 相同的模式）
+        self._subscribers: dict[str, set] = {}
+        self._listener_task = None
+
+    async def _ensure_connected(self) -> None:
+        if not self._connected:
+            await self._backend.connect()
+            self._listener_task = __import__("asyncio").create_task(self._listener())
+            self._connected = True
+            logger.debug(f"Redis Cluster 通道已连接: {self._mask_url(self._url)}")
+
+    def _mask_url(self, url: str) -> str:
+        if "@" in url:
+            parts = url.split("@")
+            prefix = parts[0]
+            suffix = parts[1]
+            if "://" in prefix:
+                scheme = prefix.split("://")[0]
+                return f"{scheme}://***@{suffix}"
+        return url
+
+    async def _listener(self) -> None:
+        """监听后端消息，分发到订阅者。"""
+        import asyncio
+        while True:
+            try:
+                event = await self._backend.next_published()
+                channel = event.channel
+                if channel in self._subscribers:
+                    for queue in list(self._subscribers[channel]):
+                        await queue.put(event)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.warning(f"Redis Cluster listener error: {e}")
+
+    async def publish(self, channel: str, message: ChannelMessage) -> None:
+        await self._ensure_connected()
+        message.channel = channel
+        data = {
+            "data": message.data,
+            "event": message.event,
+            "id": message.id,
+            "channel": message.channel,
+            "timestamp": message.timestamp.isoformat(),
+        }
+        await self._backend.publish(channel, json.dumps(data))
+
+    async def subscribe(self, channel: str) -> AsyncIterator[ChannelMessage]:
+        import asyncio
+        await self._ensure_connected()
+        
+        queue: asyncio.Queue = asyncio.Queue()
+        
+        try:
+            # 首个订阅者时订阅 Redis
+            if channel not in self._subscribers:
+                await self._backend.subscribe(channel)
+                self._subscribers[channel] = set()
+            self._subscribers[channel].add(queue)
+            
+            while True:
+                event = await queue.get()
+                try:
+                    data = json.loads(event.message)
+                    yield ChannelMessage(
+                        data=data.get("data"),
+                        event=data.get("event"),
+                        id=data.get("id"),
+                        channel=data.get("channel") or channel,
+                        timestamp=datetime.fromisoformat(data["timestamp"])
+                        if data.get("timestamp")
+                        else datetime.now(),
+                    )
+                except (json.JSONDecodeError, KeyError, TypeError) as e:
+                    logger.warning(f"解析通道消息失败: {e}")
+        finally:
+            if channel in self._subscribers:
+                self._subscribers[channel].discard(queue)
+                if not self._subscribers[channel]:
+                    del self._subscribers[channel]
+                    try:
+                        await self._backend.unsubscribe(channel)
+                    except Exception:
+                        pass
+
+    async def psubscribe(self, pattern: str) -> AsyncIterator[ChannelMessage]:
+        raise NotImplementedError(
+            "Redis Cluster Sharded Pub/Sub 不支持模式订阅。"
+            "请使用具体的 channel 名称。"
+        )
+
+    async def unsubscribe(self, channel: str) -> None:
+        pass  # subscribe() 的 finally 块自动处理
+
+    async def close(self) -> None:
+        if self._connected:
+            if self._listener_task:
+                self._listener_task.cancel()
+            await self._backend.disconnect()
+            self._connected = False
+            self._subscribers.clear()
+            logger.debug("Redis Cluster 通道已关闭")
+
+
+__all__ = ["RedisClusterChannel"]

{aury_boot-0.0.40 → aury_boot-0.0.41}/aury/boot/infrastructure/channel/base.py

@@ -18,6 +18,8 @@ class ChannelBackend(Enum):
 
     # Broadcaster 统一后端（支持 memory/redis/kafka/postgres，通过 URL scheme 区分）
     BROADCASTER = "broadcaster"
+    # Redis Cluster + Sharded Pub/Sub (Redis 7.0+)，使用 coredis 库
+    REDIS_CLUSTER = "redis_cluster"
     # 未来扩展
     RABBITMQ = "rabbitmq"
     ROCKETMQ = "rocketmq"

{aury_boot-0.0.40 → aury_boot-0.0.41}/aury/boot/infrastructure/channel/manager.py

@@ -10,6 +10,7 @@ from collections.abc import AsyncIterator
 from aury.boot.common.logging import logger
 
 from .backends.broadcaster import BroadcasterChannel
+from .backends.redis_cluster_channel import RedisClusterChannel
 from .base import ChannelBackend, ChannelMessage, IChannel
 
 
@@ -93,6 +94,7 @@ class ChannelManager:
             url: 连接 URL，支持：
                 - memory:// - 内存后端（单进程，默认）
                 - redis://host:port/db - Redis Pub/Sub
+                - redis-cluster://[password@]host:port - Redis Cluster (Sharded Pub/Sub)
                 - kafka://host:port - Apache Kafka
                 - postgres://user:pass@host/db - PostgreSQL
 
@@ -103,15 +105,21 @@ class ChannelManager:
             logger.warning(f"通道管理器 [{self.name}] 已初始化，跳过")
             return self
 
-        # 处理字符串类型的 backend
+        # 根据 URL scheme 自动选择后端
         if isinstance(backend, str):
             backend = ChannelBackend(backend.lower())
+        
+        # 自动检测 redis-cluster:// scheme
+        if url.startswith("redis-cluster://"):
+            backend = ChannelBackend.REDIS_CLUSTER
 
         self._backend_type = backend
         self._url = url
 
         if backend == ChannelBackend.BROADCASTER:
             self._backend = BroadcasterChannel(url)
+        elif backend == ChannelBackend.REDIS_CLUSTER:
+            self._backend = RedisClusterChannel(url)
         elif backend in (ChannelBackend.RABBITMQ, ChannelBackend.ROCKETMQ):
             raise NotImplementedError(f"{backend.value} 后端暂未实现")
         else: