aury-boot 0.0.4__py3-none-any.whl → 0.0.7__py3-none-any.whl

aury/boot/infrastructure/channel/backends/redis.py

@@ -0,0 +1,88 @@
+"""Redis 通道后端。
+
+适用于多进程/多实例场景，支持跨进程通信。
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from datetime import datetime
+import json
+from typing import TYPE_CHECKING
+
+from aury.boot.common.logging import logger
+
+from ..base import ChannelMessage, IChannel
+
+if TYPE_CHECKING:
+    from aury.boot.infrastructure.clients.redis import RedisClient
+
+
+class RedisChannel(IChannel):
+    """Redis 通道实现。
+
+    使用 Redis Pub/Sub 实现跨进程的发布/订阅。
+    """
+
+    def __init__(self, redis_client: RedisClient) -> None:
+        """初始化 Redis 通道。
+
+        Args:
+            redis_client: RedisClient 实例
+        """
+        self._client = redis_client
+        self._pubsub = None
+
+    async def publish(self, channel: str, message: ChannelMessage) -> None:
+        """发布消息到通道。"""
+        message.channel = channel
+        # 序列化消息
+        data = {
+            "data": message.data,
+            "event": message.event,
+            "id": message.id,
+            "channel": message.channel,
+            "timestamp": message.timestamp.isoformat(),
+        }
+        await self._client.connection.publish(channel, json.dumps(data))
+
+    async def subscribe(self, channel: str) -> AsyncIterator[ChannelMessage]:
+        """订阅通道。"""
+        pubsub = self._client.connection.pubsub()
+        await pubsub.subscribe(channel)
+
+        try:
+            async for raw_message in pubsub.listen():
+                if raw_message["type"] == "message":
+                    try:
+                        data = json.loads(raw_message["data"])
+                        message = ChannelMessage(
+                            data=data.get("data"),
+                            event=data.get("event"),
+                            id=data.get("id"),
+                            channel=data.get("channel"),
+                            timestamp=datetime.fromisoformat(data["timestamp"])
+                            if data.get("timestamp")
+                            else datetime.now(),
+                        )
+                        yield message
+                    except (json.JSONDecodeError, KeyError) as e:
+                        logger.warning(f"解析通道消息失败: {e}")
+        finally:
+            await pubsub.unsubscribe(channel)
+            await pubsub.close()
+
+    async def unsubscribe(self, channel: str) -> None:
+        """取消订阅通道。"""
+        if self._pubsub:
+            await self._pubsub.unsubscribe(channel)
+
+    async def close(self) -> None:
+        """关闭通道。"""
+        if self._pubsub:
+            await self._pubsub.close()
+            self._pubsub = None
+        logger.debug("Redis 通道已关闭")
+
+
+__all__ = ["RedisChannel"]

aury/boot/infrastructure/channel/base.py

@@ -0,0 +1,92 @@
+"""通道基础接口定义。
+
+提供流式通道的抽象接口，用于 SSE、WebSocket 等实时通信场景。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class ChannelBackend(Enum):
+    """通道后端类型。"""
+
+    MEMORY = "memory"
+    REDIS = "redis"
+
+
+@dataclass
+class ChannelMessage:
+    """通道消息。"""
+
+    data: Any
+    event: str | None = None
+    id: str | None = None
+    channel: str | None = None
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def to_sse(self) -> str:
+        """转换为 SSE 格式。"""
+        lines = []
+        if self.id:
+            lines.append(f"id: {self.id}")
+        if self.event:
+            lines.append(f"event: {self.event}")
+        # data 可能是多行
+        data_str = str(self.data) if not isinstance(self.data, str) else self.data
+        for line in data_str.split("\n"):
+            lines.append(f"data: {line}")
+        lines.append("")  # 空行结束
+        return "\n".join(lines)
+
+
+class IChannel(ABC):
+    """通道接口。"""
+
+    @abstractmethod
+    async def publish(self, channel: str, message: ChannelMessage) -> None:
+        """发布消息到通道。
+
+        Args:
+            channel: 通道名称
+            message: 消息对象
+        """
+        ...
+
+    @abstractmethod
+    async def subscribe(self, channel: str) -> AsyncIterator[ChannelMessage]:
+        """订阅通道。
+
+        Args:
+            channel: 通道名称
+
+        Yields:
+            ChannelMessage: 接收到的消息
+        """
+        ...
+
+    @abstractmethod
+    async def unsubscribe(self, channel: str) -> None:
+        """取消订阅通道。
+
+        Args:
+            channel: 通道名称
+        """
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """关闭通道连接。"""
+        ...
+
+
+__all__ = [
+    "ChannelBackend",
+    "ChannelMessage",
+    "IChannel",
+]

aury/boot/infrastructure/channel/manager.py

@@ -0,0 +1,203 @@
+"""通道管理器 - 命名多实例模式。
+
+提供统一的通道管理接口，支持多后端和多实例。
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+from aury.boot.common.logging import logger
+
+from .backends.memory import MemoryChannel
+from .backends.redis import RedisChannel
+from .base import ChannelBackend, ChannelMessage, IChannel
+
+if TYPE_CHECKING:
+    from aury.boot.infrastructure.clients.redis import RedisClient
+
+
+class ChannelManager:
+    """通道管理器（命名多实例）。
+
+    提供统一的通道管理接口，支持：
+    - 多实例管理（如 sse、notification 各自独立）
+    - 多后端支持（memory、redis）
+    - 发布/订阅模式
+
+    使用示例:
+        # 默认实例
+        channel = ChannelManager.get_instance()
+        await channel.initialize(backend="memory")
+
+        # 命名实例
+        sse_channel = ChannelManager.get_instance("sse")
+        notification_channel = ChannelManager.get_instance("notification")
+
+        # 发布消息
+        await channel.publish("events", ChannelMessage(data="hello"))
+
+        # 订阅消息
+        async for msg in channel.subscribe("events"):
+            print(msg.data)
+    """
+
+    _instances: dict[str, ChannelManager] = {}
+
+    def __init__(self, name: str = "default") -> None:
+        """初始化通道管理器。
+
+        Args:
+            name: 实例名称
+        """
+        self.name = name
+        self._backend: IChannel | None = None
+        self._backend_type: ChannelBackend | None = None
+        self._initialized: bool = False
+
+    @classmethod
+    def get_instance(cls, name: str = "default") -> ChannelManager:
+        """获取指定名称的实例。
+
+        Args:
+            name: 实例名称，默认为 "default"
+
+        Returns:
+            ChannelManager: 通道管理器实例
+        """
+        if name not in cls._instances:
+            cls._instances[name] = cls(name)
+        return cls._instances[name]
+
+    @classmethod
+    def reset_instance(cls, name: str | None = None) -> None:
+        """重置实例（仅用于测试）。
+
+        Args:
+            name: 要重置的实例名称。如果为 None，则重置所有实例。
+
+        注意：调用此方法前应先调用 cleanup() 释放资源。
+        """
+        if name is None:
+            cls._instances.clear()
+        elif name in cls._instances:
+            del cls._instances[name]
+
+    async def initialize(
+        self,
+        backend: ChannelBackend | str = ChannelBackend.MEMORY,
+        *,
+        redis_client: RedisClient | None = None,
+        max_subscribers: int = 1000,
+    ) -> ChannelManager:
+        """初始化通道（链式调用）。
+
+        Args:
+            backend: 后端类型
+            redis_client: Redis 客户端（当 backend=redis 时需要）
+            max_subscribers: 内存后端的最大订阅者数量
+
+        Returns:
+            self: 支持链式调用
+        """
+        if self._initialized:
+            logger.warning(f"通道管理器 [{self.name}] 已初始化，跳过")
+            return self
+
+        # 处理字符串类型的 backend
+        if isinstance(backend, str):
+            backend = ChannelBackend(backend.lower())
+
+        self._backend_type = backend
+
+        if backend == ChannelBackend.MEMORY:
+            self._backend = MemoryChannel(max_subscribers=max_subscribers)
+        elif backend == ChannelBackend.REDIS:
+            if redis_client is None:
+                raise ValueError("Redis 通道需要提供 redis_client 参数")
+            self._backend = RedisChannel(redis_client)
+        else:
+            raise ValueError(f"不支持的通道后端: {backend}")
+
+        self._initialized = True
+        logger.info(f"通道管理器 [{self.name}] 初始化完成: {backend.value}")
+        return self
+
+    @property
+    def backend(self) -> IChannel:
+        """获取通道后端。"""
+        if self._backend is None:
+            raise RuntimeError(
+                f"通道管理器 [{self.name}] 未初始化，请先调用 initialize()"
+            )
+        return self._backend
+
+    @property
+    def backend_type(self) -> str:
+        """获取当前后端类型。"""
+        return self._backend_type.value if self._backend_type else "unknown"
+
+    @property
+    def is_initialized(self) -> bool:
+        """检查是否已初始化。"""
+        return self._initialized
+
+    async def publish(
+        self,
+        channel: str,
+        message: ChannelMessage | str | dict,
+        *,
+        event: str | None = None,
+    ) -> None:
+        """发布消息到通道。
+
+        Args:
+            channel: 通道名称
+            message: 消息内容（ChannelMessage、字符串或字典）
+            event: 事件类型（当 message 不是 ChannelMessage 时使用）
+        """
+        if isinstance(message, ChannelMessage):
+            msg = message
+        elif isinstance(message, dict):
+            msg = ChannelMessage(data=message, event=event)
+        else:
+            msg = ChannelMessage(data=str(message), event=event)
+
+        await self.backend.publish(channel, msg)
+
+    async def subscribe(self, channel: str) -> AsyncIterator[ChannelMessage]:
+        """订阅通道。
+
+        Args:
+            channel: 通道名称
+
+        Yields:
+            ChannelMessage: 接收到的消息
+        """
+        async for message in self.backend.subscribe(channel):
+            yield message
+
+    async def unsubscribe(self, channel: str) -> None:
+        """取消订阅通道。
+
+        Args:
+            channel: 通道名称
+        """
+        await self.backend.unsubscribe(channel)
+
+    async def cleanup(self) -> None:
+        """清理资源，关闭通道。"""
+        if self._backend:
+            await self._backend.close()
+            self._backend = None
+            self._initialized = False
+            logger.info(f"通道管理器 [{self.name}] 已关闭")
+
+    def __repr__(self) -> str:
+        """字符串表示。"""
+        status = "initialized" if self._initialized else "not initialized"
+        return f"<ChannelManager name={self.name} backend={self.backend_type} status={status}>"
+
+
+__all__ = ["ChannelManager"]

aury/boot/infrastructure/clients/__init__.py

@@ -0,0 +1,22 @@
+"""客户端模块 - 外部服务连接管理。
+
+提供统一的外部服务客户端，支持多实例。
+
+包含:
+- redis: Redis 客户端
+- rabbitmq: RabbitMQ 客户端
+"""
+
+from __future__ import annotations
+
+from .rabbitmq import RabbitMQClient, RabbitMQConfig
+from .redis import RedisClient, RedisConfig
+
+__all__ = [
+    # RabbitMQ
+    "RabbitMQClient",
+    "RabbitMQConfig",
+    # Redis
+    "RedisClient",
+    "RedisConfig",
+]

aury/boot/infrastructure/clients/rabbitmq/__init__.py

@@ -0,0 +1,9 @@
+"""RabbitMQ 客户端模块。
+
+提供 RabbitMQ 连接的多实例管理。
+"""
+
+from .config import RabbitMQConfig
+from .manager import RabbitMQClient
+
+__all__ = ["RabbitMQClient", "RabbitMQConfig"]

aury/boot/infrastructure/clients/rabbitmq/config.py

@@ -0,0 +1,46 @@
+"""RabbitMQ 客户端配置。"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class RabbitMQConfig(BaseModel):
+    """RabbitMQ 连接配置。
+    
+    Attributes:
+        url: AMQP 连接 URL，如 amqp://guest:guest@localhost:5672/
+        heartbeat: 心跳间隔（秒）
+        connection_timeout: 连接超时（秒）
+        blocked_connection_timeout: 阻塞连接超时（秒）
+        prefetch_count: 预取消息数量
+        publisher_confirms: 是否启用发布确认
+    """
+    
+    url: str = Field(
+        default="amqp://guest:guest@localhost:5672/",
+        description="AMQP 连接 URL"
+    )
+    heartbeat: int = Field(
+        default=60,
+        description="心跳间隔（秒）"
+    )
+    connection_timeout: float = Field(
+        default=10.0,
+        description="连接超时（秒）"
+    )
+    blocked_connection_timeout: float = Field(
+        default=300.0,
+        description="阻塞连接超时（秒）"
+    )
+    prefetch_count: int = Field(
+        default=10,
+        description="预取消息数量（QoS）"
+    )
+    publisher_confirms: bool = Field(
+        default=True,
+        description="是否启用发布确认"
+    )
+
+
+__all__ = ["RabbitMQConfig"]