"""宿主启动编排器。 本模块是编排层的启动编排入口，按顺序装配渠道网关的所有 组件。关键步骤失败必须终止启动并报告原因（INV-I5）， 插件加载失败不得终止启动，必须触发优雅降级。 启动顺序不可颠倒： 1. 加载渠道配置（INF-009：配置缺失或类型不符必须抛异常） 2. ``ensure_channel_schema()`` 初始化渠道 schema（INV-I5：失败必须抛异常） 3. 初始化注册中心 + EventBus + 领域服务（注册到 DI 容器） 4. 加载并初始化被驱动适配器（INF-010：应用级适配器连通性检查） 5. 加载并初始化渠道插件（按依赖拓扑，失败记录警告继续） 6. 装配管道（INF-011：注入锚点格式校验） 7. 注册驱动适配器（开始接受流量） 8. 标记宿主为 ready（INF-012：与步骤 7 紧邻，对齐规范 §15.1， 后台任务启动置于 ready 之后） 9. 启动失败插件自动重载（FR-36） 10. 启动传输引擎管理器（入站Worker） 注：Outbox 恢复扫描（FR-22）、配对过期扫描（FR-33）与审计日志保留期 清理（FR-34）已迁移至 scheduler worker 的 handler，不再由 api 进程后台 任务执行，避免共享 ``AsyncSession`` 并发使用与锁 TTL 不匹配问题。 """ from __future__ import annotations import asyncio from collections.abc import Awaitable, Callable, Coroutine, Sequence from typing import Any, Protocol from yuxi.channels.application.extension.config_source_registry import ( ConfigSourceRegistry, ) from yuxi.channels.application.extension.event_bus import EventBus from yuxi.channels.application.extension.event_subscription_registry import ( EventSubscriptionRegistry, ) from yuxi.channels.application.extension.stage_slot_registry import StageSlotRegistry from yuxi.channels.application.health.health_aggregator import HealthAggregator from yuxi.channels.application.lifecycle.config_scope_registry import ( ConfigScopeRegistry, ) from yuxi.channels.application.lifecycle.plugin_dependency_resolver import ( PluginDependencyResolver, ) from yuxi.channels.application.lifecycle.plugin_lifecycle_manager import ( PluginLifecycleManager, ) from yuxi.channels.application.lifecycle.route_binding_loader import ( RouteMatchRegistryLoader, ) from yuxi.channels.application.lifecycle.sensitive_field_registry import ( SensitiveFieldRegistry, ) from yuxi.channels.application.pipeline.stage_slot_injector import StageSlotInjector from yuxi.channels.application.transport import TransportManager from yuxi.channels.contract.dtos.lifecycle import LifecycleResult from yuxi.channels.contract.dtos.plugin import DomainEvent from yuxi.channels.contract.dtos.route_events import ROUTE_BINDING_CHANGED from yuxi.channels.contract.errors import ( ConfigValidationError, DependencyError, Error, InternalError, ) from yuxi.channels.contract.errors.server import OperationTimeoutError from yuxi.channels.contract.plugin.extension_point import EventSubscription from yuxi.channels.contract.plugin.manifest import ChannelManifest, FailurePolicy from yuxi.channels.contract.ports.driven.config_port import ConfigPort from yuxi.channels.contract.ports.driven.event_publisher_port import EventPublisherPort from yuxi.channels.contract.ports.driven.logger_port import LoggerPort from yuxi.channels.contract.ports.driven.persistence_port import PersistencePort from yuxi.channels.contract.ports.driven.pingable_port import PingablePort from yuxi.channels.core.event.config import configureSensitiveFieldRegistry from yuxi.channels.core.registry.command_registry import CommandRegistryTable from yuxi.channels.core.registry.plugin_registry import PluginRegistry from yuxi.channels.core.registry.route_match_registry import RouteMatchRegistry from yuxi.channels.core.service.common_command_adapter import registerCommonCommands from yuxi.channels.infrastructure.dependency_injection import ( DependencyInjectionContainer, ) __all__ = [ "HostBootstrap", ] class _EnsureSchemaPort(Protocol): """渠道 schema 初始化端口（局部 Protocol）。 ``PostgresManager`` 满足此 Protocol（提供 ``ensure_channel_schema`` 方法）。 使用局部 Protocol 避免在 contract 层新增端口；``PostgresManager`` 位于 storage 层，不属于 channels 四层架构，直接依赖会破坏分层边界。 """ async def ensure_channel_schema(self) -> None: """确保渠道网关 schema 就绪。""" ... class _RouteBindingChangedHandler: """``RouteBindingChanged`` 领域事件处理器。 订阅 ``RouteBindingChanged`` 事件，调用 ``RouteMatchRegistryLoader.reloadAccount`` 增量刷新指定账户的路由绑定规则。作为内置订阅者在 ``HostBootstrap._loadRouteBindingsFromDB`` 中注册到 EventBus。 handler 异常由 ``EventBus.publish`` 捕获并记录警告日志，不中断其他 订阅者（FR-36），故本处理器不添加 try/except 防御。 """ def __init__(self, loader: RouteMatchRegistryLoader) -> None: self._loader = loader async def handle(self, event: DomainEvent) -> None: """处理 ``RouteBindingChanged`` 事件，刷新对应账户的路由绑定。 从事件 payload 提取 ``channel_type`` 与 ``account_id``，调用 ``loader.reloadAccount`` 增量刷新注册表。payload 缺少必要字段时 静默跳过（事件发布方契约保证字段完整，此处防御性检查）。 """ payload = event.payload channel_type = payload.get("channel_type") account_id = payload.get("account_id") if not channel_type or not account_id: return await self._loader.reloadAccount(str(channel_type), str(account_id)) class HostBootstrap: """宿主启动编排器。 按顺序装配渠道网关所有组件（INV-I5）。 启动顺序不可颠倒： 1. 加载配置 2. ``ensure_channel_schema()`` 初始化渠道 schema 3. 初始化注册中心 + EventBus + 领域服务 4. 加载并初始化被驱动适配器 5. 加载路由绑定规则到 ``RouteMatchRegistry``（DB → 内存注册表） 6. 加载并初始化渠道插件（按依赖拓扑） 7. 装配管道（注入插件阶段） 8. 注册驱动适配器（开始接受流量） 9. 标记宿主为 ready（INF-012：与步骤 8 紧邻，对齐规范 §15.1） 10. 启动失败插件自动重载（FR-36） 11. 启动传输引擎管理器 关键约束： - 关键步骤（配置加载、Schema 初始化、核心初始化、被驱动适配器初始化） 失败必须终止启动并报告原因（INV-I5）。 - 插件加载失败不得终止启动，记录警告并继续，触发优雅降级。 - 每步有超时保护，关键步骤超时抛 ``TimeoutError`` 终止启动。 - 异常处理保留原始错误上下文（INV-7），使用 ``raise ... from e``。 注：Outbox 恢复扫描（FR-22）、配对过期扫描（FR-33）与审计日志保留期 清理（FR-34）已迁移至 scheduler worker handler，不在本类启动。 """ #: Schema 初始化超时（秒） _SCHEMA_INIT_TIMEOUT: float = 60.0 #: 被驱动适配器初始化超时（秒） _DRIVEN_ADAPTER_INIT_TIMEOUT: float = 30.0 #: 配置加载超时（秒，INF-009） _CONFIG_LOAD_TIMEOUT: float = 30.0 #: 插件发现超时（秒） _PLUGIN_DISCOVER_TIMEOUT: float = 60.0 #: 单个插件加载超时（秒） # 注：必须大于内部 onInit 60s + onStart 60s = 120s 之和，否则外部超时 # 会先于内部 hook 超时触发，取消 ``_handle_failure`` 导致插件状态 # 不一致（P1-5） _PLUGIN_LOAD_TIMEOUT: float = 180.0 #: 驱动适配器注册超时（秒） _DRIVING_ADAPTER_REGISTER_TIMEOUT: float = 30.0 #: 路由绑定规则加载超时（秒）：启动时从 DB 拉取启用规则到注册表 _ROUTE_BINDING_LOAD_TIMEOUT: float = 30.0 #: 后台任务启动探测窗口（秒）：create_task 后短暂等待以捕获启动即失败 _TASK_STARTUP_PROBE_TIMEOUT: float = 0.5 def __init__( self, ensure_schema: _EnsureSchemaPort, di_container: DependencyInjectionContainer, plugin_dir: str, event_bus: EventBus, stage_slot_registry: StageSlotRegistry, event_subscription_registry: EventSubscriptionRegistry, config_source_registry: ConfigSourceRegistry, plugin_lifecycle_manager: PluginLifecycleManager, plugin_dependency_resolver: PluginDependencyResolver, stage_slot_injector: StageSlotInjector, health_aggregator: HealthAggregator, transport_manager: TransportManager, logger: LoggerPort, config_port: ConfigPort, driving_adapter_registrar: Callable[[], Awaitable[None]] | None = None, driving_adapter_unregistrar: Callable[[], Awaitable[None]] | None = None, app_driven_adapters: Sequence[Any] | None = None, ) -> None: """初始化宿主启动编排器。 Args: ensure_schema: 渠道 schema 初始化端口（``PostgresManager`` 满足 此 Protocol，提供 ``ensure_channel_schema`` 方法）。 di_container: 依赖注入容器，用于注册应用级单例。 plugin_dir: 插件目录路径，供 ``discover`` 扫描。 event_bus: 事件总线，注册到 DI 容器供领域事件分发。 stage_slot_registry: 阶段槽位注册中心。 event_subscription_registry: 事件订阅注册中心。 config_source_registry: 配置源注册中心。 plugin_lifecycle_manager: 插件生命周期管理器，编排 discover/load。 注册到 DI 容器供 ``PluginLifecycleService`` 委托调用。 plugin_dependency_resolver: 插件依赖解析器，Kahn 拓扑排序。 stage_slot_injector: 管道阶段插槽注入器。 health_aggregator: 健康状态聚合器，注册到 DI 容器供 ``HealthCheckService`` 委托调用。 logger: 日志端口，记录启动过程。 config_port: 配置被驱动端口（INF-009），启动期 ``_loadConfig`` 调用 ``getSchema`` 验证配置端口可用与 schema 已加载，配置 缺失或不可用必须终止启动（INV-I5 / §13.1）。 driving_adapter_registrar: 驱动适配器注册回调（可选），由调用方 提供，在步骤 7 调用以开始接受流量。为 ``None`` 时步骤 7 记录 告警并跳过（驱动适配器尚未接线）。 driving_adapter_unregistrar: 驱动适配器注销回调（可选），与 ``driving_adapter_registrar`` 对称，由调用方提供。当启动失败 回滚且 ``_driving_registered`` 为 ``True`` 时调用，以注销已 注册的驱动适配器并停止接收新流量。为 ``None`` 时回滚跳过 驱动适配器注销步骤（仅当调用方未提供注销能力时使用）。 app_driven_adapters: 应用级被驱动适配器列表（可选，INF-010）。 包含 ``RedisCacheAdapter`` / ``ChannelPersistenceAdapter`` / ``ARQQueueAdapter`` / ``RedisConfigAdapter`` 等跨请求共享的 应用级适配器实例。``_initDrivenAdapters`` 步骤对每个适配器 执行连通性检查（``ping()`` 或等效），失败抛 ``DependencyError`` 终止启动。为 ``None`` 或空时跳过连通性检查（向后兼容）。 """ self._ensure_schema = ensure_schema self._di = di_container self._plugin_dir = plugin_dir self._event_bus = event_bus self._stage_slot_registry = stage_slot_registry self._event_subscription_registry = event_subscription_registry self._config_source_registry = config_source_registry self._plugin_lifecycle = plugin_lifecycle_manager self._resolver = plugin_dependency_resolver self._stage_slot_injector = stage_slot_injector self._health_aggregator = health_aggregator self._transport_manager = transport_manager self._logger = logger self._config_port = config_port self._driving_adapter_registrar = driving_adapter_registrar self._driving_adapter_unregistrar = driving_adapter_unregistrar self._app_driven_adapters: tuple[Any, ...] = tuple(app_driven_adapters) if app_driven_adapters else () self._ready = False # 启动进行中标志：防止 ``bootstrap`` 并发或重复调用导致状态混乱 # （如后台任务引用被覆盖产生孤儿任务、DI 容器重复注册等）。 self._bootstrapping = False self._plugin_reload_task: asyncio.Task[None] | None = None self._transport_manager_task: asyncio.Task[None] | None = None # 路由绑定加载器：``_loadRouteBindingsFromDB`` 中构造，供 # ``_RouteBindingChangedHandler`` 持有以处理增量刷新事件。 self._route_binding_loader: RouteMatchRegistryLoader | None = None # 启动步骤完成跟踪标志（INF-013）：用于 ``_rollback`` 判断哪些步骤 # 已成功执行需逆序回滚。仅在对应步骤成功路径末尾置 ``True``，失败 # 路径保持 ``False`` 以跳过该步回滚。 self._driving_registered: bool = False self._plugins_loaded: bool = False @property def isReady(self) -> bool: """宿主是否已就绪。""" return self._ready @property def pluginReloadTask(self) -> asyncio.Task[None] | None: """失败插件自动重载后台任务（供 ``HostShutdown`` 取消）。""" return self._plugin_reload_task @property def transportManagerTask(self) -> asyncio.Task[None] | None: """传输引擎管理器后台任务（供 ``HostShutdown`` 取消）。""" return self._transport_manager_task async def bootstrap(self) -> None: """执行启动编排。 关键步骤（Schema 初始化、核心初始化、被驱动适配器初始化） 失败必须抛异常导致宿主启动失败（INV-I5）。插件加载失败记录 警告并继续，触发优雅降级。每步有超时保护，关键步骤超时抛 ``TimeoutError`` 终止启动。 启动序列（INF-012：步骤 7 与步骤 8 紧邻，对齐规范 §15.1， 后台任务启动置于 ``_markReady`` 之后）:: 0. _loadConfig 加载渠道配置（INF-009） 1. _initSchema 初始化渠道 schema 2. _initCore 注册中心 + EventBus + 领域服务 3. _initDrivenAdapters 被驱动适配器（含连通性检查 INF-010） 3.5 _loadRouteBindingsFromDB 加载路由绑定规则到注册表（DB → 内存） 4. _loadPlugins 渠道插件（按依赖拓扑） 5. _assemblePipelines 装配管道（含锚点校验 INF-011） 6. _registerDrivingAdapters 注册驱动适配器（开始接受流量） 7. _markReady 标记宿主为 ready 8. _startPluginReload 失败插件自动重载 Raises: Exception: 关键步骤失败时向上抛出，导致宿主启动失败（INV-I5）。 TimeoutError: 任一关键步骤超时。 InternalError: ``bootstrap`` 重复或并发调用。 """ # 入口守卫：防止重复/并发调用导致状态混乱（孤儿后台任务、DI 重复 # 注册、驱动适配器重复接线等）。启动失败后允许调用方重试，故仅在 # 进行中或已就绪时拒绝。 if self._ready: raise InternalError(message="host already bootstrapped") if self._bootstrapping: raise InternalError(message="bootstrap already in progress") self._bootstrapping = True try: await self._logger.info("宿主启动开始") # 0. 加载渠道配置（INF-009） # §13.1：配置缺失或类型不符必须在启动期失败，不得静默使用默认值。 await self._loadConfig() # 1. ensure_channel_schema() 初始化渠道 schema # INV-I5 / FF-SCHEMA-02：失败必须抛异常导致宿主启动失败 await self._initSchema() # 2. 初始化注册中心 + EventBus + 领域服务（注册到 DI 容器） await self._initCore() # 3. 加载并初始化被驱动适配器（INF-010：应用级适配器连通性检查） await self._initDrivenAdapters() # 3.5 加载路由绑定规则到 RouteMatchRegistry（DB → 内存注册表） # 并注册 RouteBindingChanged 事件订阅，供后续增量刷新 await self._loadRouteBindingsFromDB() # 4. 加载并初始化渠道插件（按依赖拓扑） # 插件失败标记 failed，触发优雅降级，不阻塞其他插件 await self._loadPlugins() # 4.5 注册通用命令（依赖已加载插件的 channel_type 列表） await self._registerCommonCommands() # 5. 装配管道（注入插件阶段） await self._assemblePipelines() # 6. 注册驱动适配器（开始接受流量） await self._registerDrivingAdapters() # 7. 标记宿主为 ready（INF-012：与步骤 6 紧邻，对齐规范 §15.1 # 要求"注册驱动适配器 → 标记 ready"不可被后台任务启动插入） await self._markReady() # 8. 启动失败插件自动重载（FR-36） await self._startPluginReload() # 9. 启动传输引擎管理器 await self._startTransportManager() await self._logger.info("宿主启动完成") except Exception as e: # 关键步骤失败（INV-I5 / INF-013）：按 §15.2 逆序回滚已启动的 # 组件（注销驱动适配器 → 停止插件 → 取消后台任务），避免资源 # 泄漏与孤儿状态。随后重新抛出原始异常，保留错误上下文（INV-7）， # 不掩盖根因。 await self._logger.error(f"宿主启动失败，执行回滚: {e}") await self._rollback() raise finally: # 无论成功或失败，重置启动进行中标志。成功后 ``_ready=True``， # 后续调用将被入口守卫拒绝；失败后允许调用方重试。 self._bootstrapping = False def _cancelBackgroundTasks(self) -> None: """取消已启动的后台任务（bootstrap 失败时回滚）。 使用 ``getattr`` 安全访问可能尚未创建的任务属性（失败可能发生在 任一后台任务启动之前），仅对未完成的任务触发取消。实际的任务等待 与异常记录由 ``HostShutdown._releaseCoreResourcesInternal`` 在关停 流程中完成，此处仅触发取消（``Task.cancel`` 为同步调度）以尽快 释放资源。 """ for task_attr in ( "pluginReloadTask", "transportManagerTask", ): task = getattr(self, task_attr, None) if task is not None and not task.done(): task.cancel() async def _startBackgroundTask( self, coro: Coroutine[Any, Any, None], name: str, log_message: str, ) -> asyncio.Task[None]: """启动后台任务并探测启动即失败（P0-2）。 创建后台任务后，通过 ``asyncio.wait`` 在短探测窗口内观察任务是否 立即失败（未捕获异常在首次 ``await`` 前抛出）。正常运行的任务 （进入循环体）不触发探测失败，返回 Task 对象供调用方持有。 任务注册 ``done_callback`` 以捕获探测窗口之外的意外结束（如 后台循环任务因未预期 bug 退出），避免任务静默死亡无人感知。 取消触发的结束不在 callback 中记录（属正常关停）。 Args: coro: 后台任务协程（如 ``transport_manager.run()``）。 name: 任务名称，用于日志与 ``DependencyError`` 标识。 log_message: 任务启动成功后的日志消息。 Returns: 已启动的 ``asyncio.Task`` 对象。 Raises: DependencyError: 任务在探测窗口内完成且携带异常（启动即失败）。 """ task = asyncio.create_task(coro) task.add_done_callback(self._makeBackgroundTaskDoneCallback(name)) done, _ = await asyncio.wait({task}, timeout=self._TASK_STARTUP_PROBE_TIMEOUT) if task in done and task.exception() is not None: exc = task.exception() await self._logger.error( f"后台任务启动即失败: task={name}, error={exc}", task=name, error_type=type(exc).__name__, error=str(exc), ) raise DependencyError(name, exc) from exc await self._logger.info(log_message) return task def _makeBackgroundTaskDoneCallback( self, name: str, ) -> Callable[[asyncio.Task[None]], None]: """构造后台任务结束回调。 返回的回调在任务结束时被调用： - 任务被取消（``cancelled()``）：静默返回，属正常关停流程。 - 任务正常完成（无异常）：静默返回。 - 任务携带异常：调度异步 ERROR 日志记录，避免后台循环任务内部 未预期 bug 导致任务静默死亡无人感知。 日志通过 ``asyncio.create_task`` 调度（回调为同步函数，无法直接 ``await``）。事件循环已关闭时忽略日志（关停期边缘场景）。 Args: name: 任务名称，用于日志标识。 Returns: 可注册给 ``Task.add_done_callback`` 的同步回调函数。 """ def _on_done(task: asyncio.Task[None]) -> None: if task.cancelled(): return exc = task.exception() if exc is None: return try: asyncio.create_task( self._logger.error( f"后台任务意外结束: task={name}, error={exc}", task=name, error_type=type(exc).__name__, error=str(exc), ) ) except RuntimeError: # 事件循环已关闭（关停期），无法调度日志，忽略 pass return _on_done async def _rollback(self) -> None: """启动失败时按 §15.2 逆序回滚已启动的组件（INF-013）。 回滚顺序与启动顺序相反，确保已启动的组件被正确清理： 1. **注销驱动适配器**：若 ``_driving_registered`` 为 ``True`` 且 ``driving_adapter_unregistrar`` 回调非 ``None``，调用之以停止 接收新流量。回调为 ``None`` 时跳过（调用方未提供注销能力）。 2. **停止已加载插件**：若 ``_plugins_loaded`` 为 ``True``，调用 ``PluginLifecycleManager.stopAllStartedPlugins`` 释放所有 ``STARTED`` / ``PAUSED`` 状态插件资源（封装内部迭代逻辑， 避免访问 ``_plugin_registry`` 私有属性）。 3. **取消后台任务**：复用 ``_cancelBackgroundTasks`` 取消 Outbox 扫描等已启动的后台任务。 单步回滚异常记录告警并继续，确保后续步骤仍能执行（INV-9 回退路径 完整性）。触发回滚的原始异常已由调用方 ``bootstrap`` 记录，此处 不重复记录，仅清理资源。 """ # 1. 注销驱动适配器（停止接收新流量） if self._driving_registered and self._driving_adapter_unregistrar is not None: try: await self._driving_adapter_unregistrar() except Exception as exc: await self._logger.error( "rollback: driving_adapter_unregistrar failed", error_type=type(exc).__name__, error=str(exc), ) # 2. 停止已加载的 STARTED/PAUSED 状态插件 # 通过 ``PluginLifecycleManager.stopAllStartedPlugins`` public API # 释放插件资源，避免访问其内部 ``_plugin_registry`` 私有属性 # （封装原则）。单插件停止异常已由 ``stopAllStartedPlugins`` # 内部记录告警并继续，此处仅需捕获整体异常以确保后续回滚步骤执行。 if self._plugins_loaded: try: await self._plugin_lifecycle.stopAllStartedPlugins() except Exception as exc: await self._logger.error( "rollback: stop plugins failed", error_type=type(exc).__name__, error=str(exc), ) # 3. 取消已启动的后台任务（``_cancelBackgroundTasks`` 为同步方法， # ``Task.cancel`` 仅调度取消不等待完成） try: self._cancelBackgroundTasks() except Exception as exc: await self._logger.error( "rollback: cancel background tasks failed", error_type=type(exc).__name__, error=str(exc), ) async def _initSchema(self) -> None: """初始化渠道 schema。 调用 ``ensure_channel_schema()`` 创建渠道网关表与索引。失败必须抛异常 导致宿主启动失败（INV-I5 / FF-SCHEMA-02）。 Raises: Exception: ``ensure_channel_schema`` 失败时向上抛出。 TimeoutError: schema 初始化超时。 """ try: await asyncio.wait_for( self._ensure_schema.ensure_channel_schema(), timeout=self._SCHEMA_INIT_TIMEOUT, ) except TimeoutError as e: await self._logger.error( f"渠道 schema 初始化超时: timeout={self._SCHEMA_INIT_TIMEOUT}s", ) raise OperationTimeoutError( timeout_ms=int(self._SCHEMA_INIT_TIMEOUT * 1000), message=f"渠道 schema 初始化超时: timeout={self._SCHEMA_INIT_TIMEOUT}s", ) from e except Exception as e: await self._logger.error(f"渠道 schema 初始化失败: {e}") raise # 显式失败，不掩盖根因（INV-I5） async def _loadConfig(self) -> None: """加载渠道配置（INF-009）。 调用 ``ConfigPort.getSchema`` 验证配置端口可用与 schema 已加载。 §13.1 要求"配置缺失或类型不匹配必须在启动期失败，不得静默使用 默认值"。本步骤在 schema 初始化前执行，确保后续 schema 初始化与 管道装配可基于已知有效的配置进行。 失败语义： - ``getSchema`` 返回空元组：视为配置未初始化，抛 ``ConfigValidationError`` 终止启动。 - ``getSchema`` 抛 ``DependencyError``（如 Redis 不可达）： 向上抛出原始异常（INV-I5），由 ``bootstrap`` 的统一异常处理 路径记录并触发回滚。 - ``getSchema`` 抛其他异常：包装为 ``ConfigValidationError`` 并通过 ``raise ... from e`` 保留根因（INV-7）。 - 超时：抛 ``OperationTimeoutError`` 终止启动。 Raises: ConfigValidationError: 配置 schema 为空或加载失败。 OperationTimeoutError: 配置加载超时。 """ try: schema = await asyncio.wait_for( self._config_port.getSchema(), timeout=self._CONFIG_LOAD_TIMEOUT, ) except TimeoutError as e: await self._logger.error( f"渠道配置加载超时: timeout={self._CONFIG_LOAD_TIMEOUT}s", ) raise OperationTimeoutError( timeout_ms=int(self._CONFIG_LOAD_TIMEOUT * 1000), message=f"渠道配置加载超时: timeout={self._CONFIG_LOAD_TIMEOUT}s", ) from e except DependencyError: # 依赖故障（如 Redis 不可达）已含 dep 信息，向上抛出保留根因 await self._logger.error("渠道配置加载失败：依赖故障") raise except Exception as e: await self._logger.error(f"渠道配置加载失败: {e}") raise ConfigValidationError( [f"load config schema failed: {e}"], ) from e if not schema: await self._logger.error("渠道配置 schema 为空，配置未初始化") raise ConfigValidationError( ["config schema is empty, config not initialized"], ) await self._logger.info( "渠道配置已加载", schema_field_count=len(schema), ) async def _initCore(self) -> None: """初始化注册中心 + EventBus + 领域服务。 将 framework 层应用级单例（EventBus、4 个扩展点注册中心）注册到 DI 容器，供请求级 ``create_channel_use_cases`` 解析。核心注册为同步操作 （仅注册单例到 DI 容器，无 I/O），无超时保护需求。 """ await self._registerCoreSingletons() await self._logger.info("核心组件已注册到 DI 容器") async def _registerCoreSingletons(self) -> None: """将核心组件注册到 DI 容器。 注册两类应用级单例： - framework 扩展点：EventBus、StageSlotRegistry、 EventSubscriptionRegistry、ConfigSourceRegistry - framework 编排组件：PluginLifecycleManager、HealthAggregator （供 ``create_channel_use_cases`` resolve 并注入用例服务） 同时将 ``EventPublisherPort`` 绑定到同一 ``EventBus`` 实例，使应用层 通过端口契约获取事件发布能力，满足依赖方向铁律（INV-1）与端口实现 命名空间分离（§6.3）。 核心注册表（PluginRegistry、CapabilityRegistry 等）由调用方在 构造 DI 容器时注册，此处不重复注册。 """ self._di.registerSingleton(EventBus, self._event_bus) # EventPublisherPort 绑定到 EventBus 实例（EventBus 结构化满足 # EventPublisherPort Protocol，无需显式继承），使应用层通过端口 # 契约依赖，不直接 import framework 层 EventBus。 self._di.registerSingleton(EventPublisherPort, self._event_bus) self._di.registerSingleton(StageSlotRegistry, self._stage_slot_registry) self._di.registerSingleton(EventSubscriptionRegistry, self._event_subscription_registry) self._di.registerSingleton(ConfigSourceRegistry, self._config_source_registry) self._di.registerSingleton(PluginLifecycleManager, self._plugin_lifecycle) self._di.registerSingleton(HealthAggregator, self._health_aggregator) self._di.registerSingleton(TransportManager, self._transport_manager) async def _initDrivenAdapters(self) -> None: """加载并初始化被驱动适配器（INF-010：应用级适配器连通性检查）。 被驱动适配器为请求级组件，由 ``create_driven_adapters(db)`` 按请求创建， 共享同一 ``db`` session。本步骤对 ``HostBootstrap`` 构造时传入的应用级 被驱动适配器（``cache_port`` / ``persistence_port`` / ``queue_port`` / ``config_port`` 等跨请求共享实例）执行连通性检查，确保下游依赖可达： 任一失败必须抛 ``DependencyError`` 终止启动（INV-I5），避免启动后请求期 才发现依赖故障。 连通性检查策略（``_pingAdapter``）： - 通过 ``PingablePort`` 显式契约判断适配器是否具备连通性探测能力 （INV-3 契约显式化）。 - 满足契约的适配器（``RedisCacheAdapter`` / ``ChannelPersistenceAdapter`` / ``RedisConfigAdapter`` / ``ARQQueueAdapter``）调用其 ``ping()`` 方法。 - 不满足契约的适配器（如 ``AgentRunAdapter``）显式跳过。 Raises: DependencyError: 任一应用级适配器连通性检查失败。 OperationTimeoutError: 被驱动适配器初始化超时。 """ try: await asyncio.wait_for( self._checkDrivenAdaptersConnectivity(), timeout=self._DRIVEN_ADAPTER_INIT_TIMEOUT, ) except TimeoutError as e: raise OperationTimeoutError( timeout_ms=int(self._DRIVEN_ADAPTER_INIT_TIMEOUT * 1000), message=f"被驱动适配器初始化超时: timeout={self._DRIVEN_ADAPTER_INIT_TIMEOUT}s", ) from e await self._logger.info( "应用级被驱动适配器连通性检查通过", adapter_count=len(self._app_driven_adapters), ) async def _checkDrivenAdaptersConnectivity(self) -> None: """对应用级被驱动适配器执行连通性检查（INF-010）。 遍历 ``_app_driven_adapters``，逐个调用 ``_pingAdapter``。任一适配器 连通性失败抛 ``DependencyError`` 终止启动。``_app_driven_adapters`` 为 空时仅记录请求级 factory 模式说明并返回（向后兼容未传入场景）。 """ if not self._app_driven_adapters: await self._logger.debug( "DI 容器就绪，被驱动适配器工厂可用（请求级，由 create_driven_adapters 按请求创建）", ) return for adapter in self._app_driven_adapters: await self._pingAdapter(adapter) async def _pingAdapter(self, adapter: Any) -> None: """对单个应用级被驱动适配器执行连通性检查。 通过 ``PingablePort`` 显式契约判断适配器是否具备连通性探测能力。 满足契约的适配器（``RedisCacheAdapter`` / ``ChannelPersistenceAdapter`` / ``RedisConfigAdapter`` / ``ARQQueueAdapter``）调用其 ``ping()`` 方法；不满足契约的适配器（如 ``AgentRunAdapter``）显式跳过。 ``ping()`` 返回 ``False`` 或抛异常时，抛 ``DependencyError`` 附上 适配器类型名，由 ``bootstrap`` 的统一异常处理路径记录并触发回滚。 Raises: DependencyError: 适配器 ping 返回 False 或抛异常。 """ adapter_name = type(adapter).__name__ if not isinstance(adapter, PingablePort): await self._logger.debug( f"被驱动适配器未实现 PingablePort 契约，跳过连通性检查: adapter={adapter_name}", ) return try: ok = await adapter.ping() except Exception as exc: await self._logger.error( f"被驱动适配器连通性检查异常: adapter={adapter_name}, error={exc}", adapter=adapter_name, error_type=type(exc).__name__, error=str(exc), ) raise DependencyError(adapter_name, exc) from exc if ok is False: await self._logger.error( f"被驱动适配器连通性检查失败: adapter={adapter_name}", adapter=adapter_name, ) raise DependencyError( adapter_name, Error(f"ping returned False: {adapter_name}"), ) async def _loadRouteBindingsFromDB(self) -> None: """启动时从 DB 加载路由绑定规则到 ``RouteMatchRegistry``。 从 DI 容器解析 ``RouteMatchRegistry`` 与 ``PersistencePort``（实现 ``RouteBindingRepositoryPort``），构造 ``RouteMatchRegistryLoader`` 调用 ``loadAll`` 全量加载启用状态的规则到注册表。加载完成后注册 ``RouteBindingChanged`` 事件订阅，后续路由绑定变更通过事件增量刷新 注册表。 失败语义： - DB 查询失败等异常向上抛出，终止启动（INV-I5：路由绑定规则为 ``RouteResolver`` 运行时依赖，加载失败必须显式失败）。 - 超时抛 ``OperationTimeoutError`` 终止启动。 - 单条非法规则由 loader 内部 try/except 记录 warn 跳过，不阻断 整体加载。 Raises: Exception: ``loadAll`` 失败时向上抛出（DB 故障等）。 OperationTimeoutError: 路由绑定规则加载超时。 """ registry = self._di.resolve(RouteMatchRegistry) persistence_port = self._di.resolve(PersistencePort) self._route_binding_loader = RouteMatchRegistryLoader( repo_port=persistence_port, registry=registry, logger=self._logger, ) try: loaded = await asyncio.wait_for( self._route_binding_loader.loadAll(), timeout=self._ROUTE_BINDING_LOAD_TIMEOUT, ) except TimeoutError as e: raise OperationTimeoutError( timeout_ms=int(self._ROUTE_BINDING_LOAD_TIMEOUT * 1000), message=f"路由绑定规则加载超时: timeout={self._ROUTE_BINDING_LOAD_TIMEOUT}s", ) from e await self._logger.info( "路由绑定规则已加载到注册表", loaded=loaded, ) # 注册 RouteBindingChanged 事件订阅：后续路由绑定变更通过事件 # 增量刷新注册表，保持内存注册表与 DB 一致。 self._event_bus.register( "host", EventSubscription( event_type=ROUTE_BINDING_CHANGED, handler=_RouteBindingChangedHandler(self._route_binding_loader), priority=100, failure_policy=FailurePolicy.DEGRADE, ), ) async def _loadPlugins(self) -> None: """加载并初始化渠道插件（按依赖拓扑）。 执行 ``discover`` 扫描插件目录 → ``resolve`` 拓扑排序 → 按序 ``load``。 discover/resolve 失败记录警告并跳过插件加载；单个插件 load 失败记录 警告并继续，触发优雅降级，不阻塞宿主启动。 F-01：discover 成功后，从 DI 容器解析 ``SensitiveFieldRegistry``， 调用 ``register(manifests)`` 合并插件 manifest 声明的敏感字段， 并通过 ``configureSensitiveFieldRegistry`` 注入到 ``core/event/config.py`` 模块级全局变量，供 ``ConfigChanged`` / ``ConfigRollback`` 事件序列化脱敏使用。 F-02：discover 成功后，从 DI 容器解析 ``ConfigScopeRegistry``， 调用 ``register(manifests)`` 合并插件 manifest 声明的作用域， 供 ``RedisConfigAdapter._build_key`` 校验 key→scope 一致性。 Raises: TimeoutError: discover 阶段超时。 """ # discover 扫描插件目录 try: manifests = await asyncio.wait_for( self._plugin_lifecycle.discover(self._plugin_dir), timeout=self._PLUGIN_DISCOVER_TIMEOUT, ) except TimeoutError as e: raise OperationTimeoutError( timeout_ms=int(self._PLUGIN_DISCOVER_TIMEOUT * 1000), message=f"插件发现超时: timeout={self._PLUGIN_DISCOVER_TIMEOUT}s", ) from e except Exception as e: await self._logger.warn(f"插件发现失败，跳过插件加载: {e}") return if not manifests: await self._logger.info("无插件可加载") return await self._logger.info(f"发现 {len(manifests)} 个插件") # F-01：合并插件 manifest 声明的敏感字段到 SensitiveFieldRegistry， # 并注入到 core/event/config.py 模块级全局变量。registry 在 # _register_di_singletons 中已注册为单例（预合并 CONFIG_SCHEMA）， # 此处增量合并插件声明的敏感字段。configureSensitiveFieldRegistry # 使 ConfigChanged/ConfigRollback 事件序列化时能识别插件声明的 # 敏感字段（如 bridge_url/bot_token/app_secret 等）。 sensitive_registry = self._di.resolve(SensitiveFieldRegistry) sensitive_registry.register(manifests) configureSensitiveFieldRegistry(sensitive_registry) # F-02：合并插件 manifest 声明的作用域到 ConfigScopeRegistry。 # registry 在 _register_di_singletons 中已注册为单例（预合并 # CONFIG_SCHEMA），此处增量合并插件声明的作用域。registry 通过 # dict.update 原地修改内部 dict，已持有 key_to_scope_map 只读视图的 # RedisConfigAdapter 实例立即可见更新。 config_scope_registry = self._di.resolve(ConfigScopeRegistry) config_scope_registry.register(manifests) # resolve 拓扑排序（失败则使用未排序顺序） try: sorted_manifests = self._resolver.resolve(manifests) except Exception as e: await self._logger.warn( f"插件依赖解析失败，使用未排序顺序加载: {e}", ) sorted_manifests = manifests # 按拓扑序加载 for manifest in sorted_manifests: await self._loadSinglePlugin(manifest) # INF-013：插件加载步骤完成（含优雅降级场景），置位跟踪标志。 # ``_rollback`` 据此判断是否需要停止 STARTED/PAUSED 状态插件； # 单个插件 load 失败已由 ``_loadSinglePlugin`` 记录告警并继续， # 不影响本步骤的完成状态。 self._plugins_loaded = True async def _registerCommonCommands(self) -> None: """注册通用命令到命令注册表。 从 DI 容器解析 ``PluginRegistry`` 与 ``CommandRegistryTable``， 遍历已加载插件的 channel_type 列表，为每个渠道类型注册 6 个通用 命令（/help、/model、/reset、/about、/allowlist、/approve）。 渠道特定命令优先保留，通用命令仅填充未占用的命令名。 本步骤必须在 ``_loadPlugins`` 之后执行，因为 channel_type 列表 由插件 manifest 声明，只有在插件加载后才可知。 """ plugin_registry = self._di.resolve(PluginRegistry) command_registry_table = self._di.resolve(CommandRegistryTable) channel_types = plugin_registry.listChannelTypes() registerCommonCommands(command_registry_table, channel_types) await self._logger.info( f"通用命令注册完成: {len(channel_types)} 个渠道类型", channel_count=len(channel_types), ) async def _loadSinglePlugin(self, manifest: ChannelManifest) -> None: """加载单个插件，失败记录警告并继续。 插件加载失败不阻塞宿主启动，记录警告并触发优雅降级。 Args: manifest: 渠道清单。 """ try: result: LifecycleResult = await asyncio.wait_for( self._plugin_lifecycle.load(manifest.id), timeout=self._PLUGIN_LOAD_TIMEOUT, ) except TimeoutError: await self._logger.warn( f"插件加载超时，跳过: plugin_id={manifest.id}, timeout={self._PLUGIN_LOAD_TIMEOUT}s", plugin_id=manifest.id, ) return except Exception as e: await self._logger.warn( f"插件加载异常，跳过: plugin_id={manifest.id}, error={e}", plugin_id=manifest.id, error=str(e), ) return if result.state == "failed": await self._logger.warn( f"插件加载失败，触发优雅降级: plugin_id={manifest.id}, error={result.error}", plugin_id=manifest.id, error=result.error or "", ) else: await self._logger.info( f"插件加载成功: plugin_id={manifest.id}", plugin_id=manifest.id, ) async def _assemblePipelines(self) -> None: """装配管道（注入插件阶段，INF-011：注入锚点格式校验）。 管道为请求级组件，由 ``create_channel_use_cases`` 按请求创建。阶段插槽 注入（``StageSlotInjector.inject``）在请求级管道装配时执行。本步骤在 启动期对注册中心所有声明式槽位执行一次注入验证（锚点格式合法、 ``replace`` 白名单约束、目标 ID 非空），提前发现非法锚点，避免请求期 ``inject`` 才抛 ``RuleViolationError`` 影响可用性。槽位校验为同步操作 （无 I/O），无超时保护需求。 验证失败必须抛 ``ValidationError`` 终止启动（INV-I5）。 Raises: ValidationError: 槽位锚点格式非法或 ``replace`` 用于非白名单阶段。 """ await self._validateAndLogPipelines() async def _validateAndLogPipelines(self) -> None: """校验所有声明式管道槽位锚点并记录就绪状态（INF-011）。 先调用 ``StageSlotInjector.validateAnchors`` 对所有管道的槽位锚点 做格式与白名单校验，失败抛 ``ValidationError``；通过后再记录各管道 槽位数量，供运维定位。 """ # 1. 启动期锚点注入验证（不依赖请求级 stages 列表） self._stage_slot_injector.validateAnchors() # 2. 记录已注册槽位数量 inbound_slots = self._stage_slot_registry.findByPipeline("inbound") outbound_slots = self._stage_slot_registry.findByPipeline("outbound") control_slots = self._stage_slot_registry.findByPipeline("control") await self._logger.info( "管道阶段槽位就绪（请求级注入，锚点校验通过）", inbound_slot_count=len(inbound_slots), outbound_slot_count=len(outbound_slots), control_slot_count=len(control_slots), ) async def _registerDrivingAdapters(self) -> None: """注册驱动适配器（开始接受流量）。 若调用方提供了 ``driving_adapter_registrar`` 回调，则调用之以注册 各驱动适配器（如 Webhook / Admin API / 内置 Web 渠道等，具体由 宿主接线决定）。为 ``None`` 时记录告警，宿主不开始接受流量 （驱动适配器尚未接线）。 Raises: TimeoutError: 驱动适配器注册超时。 """ if self._driving_adapter_registrar is None: await self._logger.warn( "驱动适配器注册回调未提供，宿主不开始接受流量（driving_adapter_registrar=None）", ) return try: await asyncio.wait_for( self._driving_adapter_registrar(), timeout=self._DRIVING_ADAPTER_REGISTER_TIMEOUT, ) except TimeoutError as e: raise OperationTimeoutError( timeout_ms=int(self._DRIVING_ADAPTER_REGISTER_TIMEOUT * 1000), message=f"驱动适配器注册超时: timeout={self._DRIVING_ADAPTER_REGISTER_TIMEOUT}s", ) from e await self._logger.info("驱动适配器已注册，开始接受流量") # INF-013：驱动适配器注册成功，置位跟踪标志。``_rollback`` 据此 # 判断是否需要调用 ``driving_adapter_unregistrar`` 注销驱动适配器。 self._driving_registered = True async def _startPluginReload(self) -> None: """启动失败插件自动重载后台任务（FR-36）。 以后台任务方式启动 ``PluginLifecycleManager.reloadLoop``，定时 （默认 60s 间隔）扫描 ``DegradationManager`` 中到达 ``next_retry_at`` 的失败插件并触发重载。``reloadLoop`` 内部已捕获并记录单轮扫描异常， 不阻塞宿主启动。通过 ``_startBackgroundTask`` 启动探测捕获启动即失败。 Raises: DependencyError: 后台任务启动即失败。 """ self._plugin_reload_task = await self._startBackgroundTask( self._plugin_lifecycle.reloadLoop(interval=60.0), name="plugin_reload", log_message="失败插件自动重载已启动（后台任务，间隔 60s）", ) async def _startTransportManager(self) -> None: """启动传输引擎管理器。 以后台任务方式启动 ``TransportManager.start()``，统一管理所有 渠道账户的入站传输 Worker（Puller/Stream）。通过 ``_startBackgroundTask`` 启动探测捕获启动即失败。 Raises: DependencyError: 后台任务启动即失败。 """ self._transport_manager_task = await self._startBackgroundTask( self._transport_manager.start(), name="transport_manager", log_message="传输引擎管理器已启动", ) async def _markReady(self) -> None: """标记宿主为 ready。 ``_setReadyState`` 为同步操作（仅置位标志与记录日志，无 I/O）， 无超时保护需求。 """ await self._setReadyState() async def _setReadyState(self) -> None: """设置宿主就绪状态。""" self._ready = True await self._logger.info("宿主已标记为 ready")