aury-boot 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

aury/boot/application/rpc/discovery.py

@@ -0,0 +1,218 @@
+"""服务发现模块。
+
+支持多种服务发现方式：
+- 配置文件（推荐，通过 BaseConfig.rpc_client.services）
+- DNS 解析（统一处理 K8s/Docker Compose，通过服务名自动解析）
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from aury.boot.common.logging import logger
+
+if TYPE_CHECKING:
+    from aury.boot.application.config import BaseConfig
+
+
+class ServiceDiscovery:
+    """服务发现抽象基类。
+    
+    所有服务发现实现都应该继承此类。
+    """
+    
+    def resolve(self, service_name: str) -> str | None:
+        """解析服务地址。
+        
+        Args:
+            service_name: 服务名称
+            
+        Returns:
+            str | None: 服务地址（URL），如果无法解析返回 None
+        """
+        raise NotImplementedError
+
+
+class ConfigServiceDiscovery(ServiceDiscovery):
+    """基于配置文件的服务发现。
+    
+    从配置文件中读取服务地址映射。
+    
+    配置格式：
+    ```python
+    services = {
+        "user-service": "http://user-service:8000",
+        "order-service": "http://order-service:8001",
+    }
+    ```
+    """
+    
+    def __init__(self, service_config: dict[str, str] | None = None) -> None:
+        """初始化配置服务发现。
+        
+        Args:
+            service_config: 服务配置字典 {service_name: url}
+        """
+        self._services: dict[str, str] = service_config or {}
+    
+    def resolve(self, service_name: str) -> str | None:
+        """从配置中解析服务地址。"""
+        url = self._services.get(service_name)
+        if url:
+            logger.debug(f"从配置解析服务: {service_name} -> {url}")
+            return url
+        logger.warning(f"配置中未找到服务: {service_name}")
+        return None
+    
+    def register(self, service_name: str, url: str) -> None:
+        """注册服务地址。
+        
+        Args:
+            service_name: 服务名称
+            url: 服务地址
+        """
+        self._services[service_name] = url
+        logger.info(f"注册服务: {service_name} -> {url}")
+
+
+
+
+class DNSServiceDiscovery(ServiceDiscovery):
+    """DNS 服务发现（统一处理 K8s/Docker Compose）。
+    
+    直接使用服务名进行 DNS 解析：
+    - K8s: 自动使用 service-name（K8s DNS 会在同一 namespace 内解析）
+    - Docker Compose: 直接使用 service-name
+    """
+    
+    def __init__(
+        self,
+        scheme: str = "http",
+        default_port: int = 80,
+    ) -> None:
+        """初始化 DNS 服务发现。
+        
+        Args:
+            scheme: 协议（http 或 https）
+            default_port: 默认端口
+        """
+        self._scheme = scheme
+        self._default_port = default_port
+    
+    def resolve(self, service_name: str) -> str | None:
+        """使用 DNS 解析服务地址。
+        
+        Args:
+            service_name: 服务名称（直接作为主机名，DNS 自动解析）
+        """
+        # 直接使用服务名作为主机名（DNS 自动处理）
+        url = f"{self._scheme}://{service_name}"
+        
+        if self._default_port not in (80, 443):
+            url = f"{url}:{self._default_port}"
+        
+        logger.debug(f"使用 DNS 解析服务: {service_name} -> {url}")
+        return url
+
+
+class CompositeServiceDiscovery(ServiceDiscovery):
+    """组合服务发现。
+    
+    按优先级顺序尝试多种服务发现方式：
+    1. 配置文件（最高优先级，通过 BaseConfig.rpc_client.services）
+    2. DNS 解析（统一处理 K8s/Docker Compose，自动检测环境）
+    """
+    
+    def __init__(
+        self,
+        config: "BaseConfig" | None = None,
+    ) -> None:
+        """初始化组合服务发现。
+        
+        Args:
+            config: 应用配置（BaseConfig），如果为 None，则仅使用默认配置
+        """
+        self._discoveries: list[ServiceDiscovery] = []
+        
+        # 从配置中获取 RPC 客户端设置
+        if config:
+            rpc_client_settings = config.rpc_client
+        else:
+            # 如果没有提供配置，使用默认配置
+            from aury.boot.application.config import RPCClientSettings
+            rpc_client_settings = RPCClientSettings()
+        
+        # 1. 配置文件（最高优先级）
+        if rpc_client_settings.services:
+            self._discoveries.append(ConfigServiceDiscovery(rpc_client_settings.services))
+        
+        # 2. DNS 解析（如果启用）
+        if rpc_client_settings.use_dns_fallback:
+            logger.info("启用 DNS 服务发现（统一处理 K8s/Docker Compose）")
+            self._discoveries.append(
+                DNSServiceDiscovery(
+                    scheme=rpc_client_settings.dns_scheme,
+                    default_port=rpc_client_settings.dns_port,
+                )
+            )
+    
+    def resolve(self, service_name: str) -> str | None:
+        """按优先级顺序解析服务地址。"""
+        for discovery in self._discoveries:
+            url = discovery.resolve(service_name)
+            if url:
+                return url
+        
+        logger.error(f"无法解析服务地址: {service_name}（已尝试所有服务发现方式）")
+        return None
+
+
+# 全局服务发现实例
+_global_discovery: ServiceDiscovery | None = None
+_global_config: "BaseConfig | None" = None
+
+
+def get_service_discovery(config: "BaseConfig | None" = None) -> ServiceDiscovery:
+    """获取全局服务发现实例。
+    
+    如果未初始化，使用配置创建组合服务发现。
+    
+    Args:
+        config: 应用配置（可选），如果提供则使用此配置初始化
+    
+    Returns:
+        ServiceDiscovery: 服务发现实例
+    """
+    global _global_discovery, _global_config
+    
+    # 如果提供了新配置，更新全局配置
+    if config is not None:
+        _global_config = config
+    
+    # 如果未初始化或配置已更新，重新创建
+    if _global_discovery is None or config is not None:
+        _global_discovery = CompositeServiceDiscovery(_global_config)
+    
+    return _global_discovery
+
+
+def set_service_discovery(discovery: ServiceDiscovery) -> None:
+    """设置全局服务发现实例。
+    
+    Args:
+        discovery: 服务发现实例
+    """
+    global _global_discovery
+    _global_discovery = discovery
+    logger.info("已设置全局服务发现实例")
+
+
+__all__ = [
+    "CompositeServiceDiscovery",
+    "ConfigServiceDiscovery",
+    "DNSServiceDiscovery",
+    "ServiceDiscovery",
+    "get_service_discovery",
+    "set_service_discovery",
+]
+

aury/boot/application/scheduler/__init__.py

@@ -0,0 +1,13 @@
+"""调度器启动器模块。
+
+提供调度器独立进程的启动入口。
+"""
+
+from .runner import run_scheduler, run_scheduler_sync
+
+__all__ = [
+    "run_scheduler",
+    "run_scheduler_sync",
+]
+
+

aury/boot/application/scheduler/runner.py

@@ -0,0 +1,123 @@
+"""调度器启动器。
+
+提供调度器独立进程的启动入口。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+import signal
+
+from aury.boot.application.config import BaseConfig
+from aury.boot.application.constants import ServiceType
+from aury.boot.common.logging import logger
+from aury.boot.infrastructure.scheduler import SchedulerManager
+
+
+async def run_scheduler(
+    config: BaseConfig | None = None,
+    *,
+    register_jobs: Callable[[], None] | Callable[[], Awaitable[None]] | None = None,
+) -> None:
+    """运行调度器进程（独立模式）。
+    
+    当 SERVICE_TYPE=scheduler 时，使用此函数启动独立的调度器进程。
+    
+    Args:
+        config: 应用配置（可选，默认从环境变量加载）
+        register_jobs: 注册任务的回调函数（可选）
+    
+    使用示例:
+        async def setup_jobs():
+            scheduler = SchedulerManager.get_instance()
+            scheduler.add_job(
+                func=my_task,
+                trigger="interval",
+                seconds=60
+            )
+        
+        if __name__ == "__main__":
+            asyncio.run(run_scheduler(register_jobs=setup_jobs))
+    """
+    # 加载配置
+    if config is None:
+        config = BaseConfig()
+    
+    service_config = config.service
+    
+    # 验证服务类型
+    try:
+        service_type = ServiceType(service_config.service_type.lower())
+    except ValueError as e:
+        raise ValueError(f"无效的服务类型: {service_config.service_type}") from e
+    
+    if service_type != ServiceType.SCHEDULER:
+        raise ValueError(
+            f"此函数仅用于 SERVICE_TYPE=scheduler，当前类型: {service_config.service_type}"
+        )
+    
+    logger.info("启动调度器进程（独立模式）")
+    
+    # 初始化调度器
+    scheduler_manager = SchedulerManager.get_instance()
+    await scheduler_manager.initialize()
+    
+    # 注册任务
+    if register_jobs:
+        logger.info("注册定时任务...")
+        if asyncio.iscoroutinefunction(register_jobs):
+            await register_jobs()
+        else:
+            register_jobs()
+        jobs = scheduler_manager.get_jobs()
+        logger.info(f"已注册 {len(jobs)} 个定时任务")
+    else:
+        logger.warning("未提供任务注册函数，调度器将不执行任何任务")
+    
+    # 启动调度器
+    scheduler_manager.start()
+    logger.info("调度器进程已启动，等待任务执行...")
+    
+    # 设置信号处理，优雅关闭
+    def signal_handler(signum, frame):
+        logger.info(f"收到信号 {signum}，正在关闭调度器...")
+        scheduler_manager.shutdown()
+        logger.info("调度器已关闭")
+        asyncio.get_event_loop().stop()
+    
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+    
+    # 保持进程运行
+    try:
+        # 使用 asyncio.Event 保持进程运行
+        stop_event = asyncio.Event()
+        await stop_event.wait()
+    except KeyboardInterrupt:
+        logger.info("收到中断信号，正在关闭...")
+        scheduler_manager.shutdown()
+        logger.info("调度器已关闭")
+
+
+def run_scheduler_sync(
+    config: BaseConfig | None = None,
+    *,
+    register_jobs: Callable[[], None] | Callable[[], Awaitable[None]] | None = None,
+) -> None:
+    """运行调度器进程（同步版本）。
+    
+    这是 run_scheduler 的同步包装，方便直接调用。
+    
+    Args:
+        config: 应用配置（可选，默认从环境变量加载）
+        register_jobs: 注册任务的回调函数（可选）
+    """
+    asyncio.run(run_scheduler(config=config, register_jobs=register_jobs))
+
+
+__all__ = [
+    "run_scheduler",
+    "run_scheduler_sync",
+]
+

aury/boot/application/server/__init__.py

@@ -0,0 +1,296 @@
+"""ASGI 服务器管理。
+
+提供 uvicorn 服务器的完整集成。
+
+包含：
+- ApplicationServer 类：服务器管理
+- run_app 函数：快速启动
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import sys
+from typing import TYPE_CHECKING, Any
+
+from aury.boot.common.logging import logger
+
+if TYPE_CHECKING:
+    from aury.boot.application.app.base import FoundationApp
+
+
+class ApplicationServer:
+    """ASGI 应用服务器。
+    
+    基于 uvicorn，提供完整的服务器管理功能。
+    
+    使用示例:
+        app = FoundationApp()
+        server = ApplicationServer(
+            app=app,
+            host="0.0.0.0",
+            port=8000,
+            workers=4,
+        )
+        server.run()
+    """
+    
+    def __init__(
+        self,
+        app: FoundationApp,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+        workers: int = 1,
+        reload: bool = False,
+        reload_dirs: list[str] | None = None,
+        loop: str = "auto",
+        http: str = "auto",
+        interface: str = "auto",
+        debug: bool = False,
+        access_log: bool = True,
+        use_colors: bool | None = None,
+        log_config: dict | None = None,
+        ssl_keyfile: str | None = None,
+        ssl_certfile: str | None = None,
+        ssl_keyfile_password: str | None = None,
+        ssl_version: int | None = None,
+        ssl_cert_reqs: int | None = None,
+        ssl_ca_certs: str | None = None,
+        ssl_ciphers: str | None = None,
+        **kwargs,
+    ) -> None:
+        """初始化服务器。
+        
+        Args:
+            app: FastAPI/FoundationApp 应用实例
+            host: 监听地址，默认 127.0.0.1
+            port: 监听端口，默认 8000
+            workers: 工作进程数，默认 1
+            reload: 是否启用热重载
+            reload_dirs: 热重载监控目录
+            loop: 事件循环实现 (auto/asyncio/uvloop)
+            http: HTTP 协议版本 (auto/h11/httptools)
+            interface: ASGI 接口版本 (auto/asgi3/asgi2)
+            debug: 是否启用调试模式
+            access_log: 是否记录访问日志
+            use_colors: 是否使用彩色输出
+            log_config: 自定义日志配置
+            ssl_keyfile: SSL 密钥文件路径
+            ssl_certfile: SSL 证书文件路径
+            ssl_keyfile_password: SSL 密钥密码
+            ssl_version: SSL 版本
+            ssl_cert_reqs: SSL 证书请求模式
+            ssl_ca_certs: SSL CA 证书文件
+            ssl_ciphers: SSL 密码套件
+            **kwargs: 传递给 uvicorn.Config 的其他参数
+        """
+        self.app = app
+        self.host = host
+        self.port = port
+        self.workers = workers
+        self.reload = reload
+        self.reload_dirs = reload_dirs
+        self.loop = loop
+        self.http = http
+        self.interface = interface
+        self.debug = debug
+        self.access_log = access_log
+        self.use_colors = use_colors
+        self.log_config = log_config or self._get_default_log_config()
+        self.ssl_keyfile = ssl_keyfile
+        self.ssl_certfile = ssl_certfile
+        self.ssl_keyfile_password = ssl_keyfile_password
+        self.ssl_version = ssl_version
+        self.ssl_cert_reqs = ssl_cert_reqs
+        self.ssl_ca_certs = ssl_ca_certs
+        self.ssl_ciphers = ssl_ciphers
+        self.extra_kwargs = kwargs
+        
+        self.server: Any = None
+    
+    def _get_default_log_config(self) -> dict:
+        """获取默认日志配置。
+        
+        整合 uvicorn 日志和框架日志。
+        """
+        import uvicorn
+        from uvicorn.config import LOGGING_CONFIG
+        
+        config = LOGGING_CONFIG.copy()
+        
+        # 调整日志格式
+        config["formatters"]["access"]["format"] = (
+            "%(asctime)s | %(client_addr)s - "
+            "%(request_line)s | %(status_code)s"
+        )
+        config["formatters"]["default"]["format"] = (
+            "%(asctime)s | %(levelname)s | %(name)s - %(message)s"
+        )
+        
+        return config
+    
+    def get_config(self) -> Any:
+        """获取 uvicorn 配置对象。
+        
+        Returns:
+            uvicorn.Config: 服务器配置
+        """
+        import uvicorn
+        
+        # 从 uvicorn 0.30.0 开始，Config.__init__ 不再接受 ``debug`` 参数，
+        # 这里仅在日志中使用 debug 标志，而不再传递给 uvicorn.Config，
+        # 以避免 "unexpected keyword argument 'debug'" 异常。
+        return uvicorn.Config(
+            app=self.app,
+            host=self.host,
+            port=self.port,
+            workers=self.workers,
+            reload=self.reload,
+            reload_dirs=self.reload_dirs,
+            loop=self.loop,
+            http=self.http,
+            interface=self.interface,
+            access_log=self.access_log,
+            use_colors=self.use_colors,
+            log_config=self.log_config,
+            ssl_keyfile=self.ssl_keyfile,
+            ssl_certfile=self.ssl_certfile,
+            ssl_keyfile_password=self.ssl_keyfile_password,
+            ssl_version=self.ssl_version,
+            ssl_cert_reqs=self.ssl_cert_reqs,
+            ssl_ca_certs=self.ssl_ca_certs,
+            ssl_ciphers=self.ssl_ciphers,
+            **self.extra_kwargs,
+        )
+    
+    def run(self) -> None:
+        """运行服务器。
+        
+        阻塞调用，服务器会一直运行直到收到中断信号。
+        """
+        import uvicorn
+        
+        config = self.get_config()
+        self.server = uvicorn.Server(config)
+        
+        # 设置信号处理
+        self._setup_signal_handlers()
+        
+        # 记录启动信息
+        self._log_startup_info()
+        
+        # 运行服务器
+        try:
+            self.server.run()
+        except KeyboardInterrupt:
+            logger.info("服务器已停止（Ctrl+C）")
+        except Exception as exc:
+            logger.error(f"服务器错误: {exc}", exc_info=True)
+            sys.exit(1)
+    
+    async def run_async(self) -> None:
+        """异步运行服务器。
+        
+        使用示例:
+            server = ApplicationServer(app)
+            await server.run_async()
+        """
+        import uvicorn
+        
+        config = self.get_config()
+        self.server = uvicorn.Server(config)
+        
+        # 记录启动信息
+        self._log_startup_info()
+        
+        # 运行服务器
+        try:
+            await self.server.serve()
+        except KeyboardInterrupt:
+            logger.info("服务器已停止")
+        except Exception as exc:
+            logger.error(f"服务器错误: {exc}", exc_info=True)
+            sys.exit(1)
+    
+    def _setup_signal_handlers(self) -> None:
+        """设置信号处理器。
+        
+        处理 SIGTERM 和 SIGINT 信号，确保优雅关闭。
+        """
+        def handle_signal(signum, frame):
+            logger.info(f"收到信号 {signum}，正在关闭...")
+            if self.server:
+                self.server.should_exit = True
+        
+        signal.signal(signal.SIGINT, handle_signal)
+        signal.signal(signal.SIGTERM, handle_signal)
+    
+    def _log_startup_info(self) -> None:
+        """记录启动信息。"""
+        protocol = "https" if self.ssl_certfile else "http"
+        url = f"{protocol}://{self.host}:{self.port}"
+        
+        logger.info(
+            f"服务器启动 | "
+            f"地址: {url} | "
+            f"工作进程: {self.workers} | "
+            f"热重载: {self.reload}"
+        )
+        
+        if self.debug:
+            logger.warning("调试模式已启用")
+        
+        if self.reload:
+            default_dirs = [os.getcwd()] if not self.reload_dirs else self.reload_dirs
+            logger.info(f"热重载监控目录: {default_dirs}")
+
+
+def run_app(
+    app: FoundationApp,
+    *,
+    host: str | None = None,
+    port: int | None = None,
+    workers: int | None = None,
+    reload: bool = False,
+    **kwargs,
+) -> None:
+    """快速运行应用。
+    
+    从环境变量或参数读取配置。
+    
+    使用示例:
+        from aury.boot.application.server import run_app
+        
+        app = FoundationApp()
+        run_app(app)
+    
+    环境变量支持:
+        SERVER_HOST: 监听地址
+        SERVER_PORT: 监听端口
+        SERVER_WORKERS: 工作进程数
+        SERVER_RELOAD: 是否热重载
+    """
+    # 从环境变量读取默认值
+    host = host or os.getenv("SERVER_HOST", "127.0.0.1")
+    port = port or int(os.getenv("SERVER_PORT", "8000"))
+    workers = workers or int(os.getenv("SERVER_WORKERS", "1"))
+    reload = reload or os.getenv("SERVER_RELOAD", "").lower() in ("true", "1", "yes")
+    
+    server = ApplicationServer(
+        app=app,
+        host=host,
+        port=port,
+        workers=workers,
+        reload=reload,
+        **kwargs,
+    )
+    server.run()
+
+
+__all__ = [
+    "ApplicationServer",
+    "run_app",
+]
+

aury/boot/commands/__init__.py

@@ -0,0 +1,30 @@
+"""命令行工具模块。
+
+统一入口: aum
+"""
+
+from __future__ import annotations
+
+# 轻量配置模块可以直接导入
+from .config import ProjectConfig, get_project_config, save_project_config
+
+
+# 延迟导入 app 和 main，避免加载重型依赖
+def __getattr__(name: str):
+    if name in ("app", "main"):
+        from .app import main as _main
+        if name == "main":
+            return _main
+        # app 通过 app 模块的 __getattr__ 获取
+        from . import app as app_module
+        return app_module.app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "app",
+    "main",
+    "ProjectConfig",
+    "get_project_config",
+    "save_project_config",
+]