Kris
742299cb07
本次提交包含多维度代码优化与功能增强： 1. 移除报告模块冗余导入与枚举，清理报表相关代码 2. 新增扫码登录支持方法与飞书适配器适配 3. 完善异常日志与健康检查信息 4. 扩展目录、配对管理、能力查询等接口 5. 优化出站管道与事务提交后钩子逻辑 6. 修复飞书消息解析与响应空值问题 7. 重构配置更新与服务账号创建逻辑 8. 统一传输错误分类契约与错误基类扩展
191 lines
7.7 KiB
Python
191 lines
7.7 KiB
Python
"""微信 iLink（ClawBot）渠道插件生命周期钩子处理。
|
||
|
||
实现 ``LifecycleHookHandler`` Protocol，管理插件级资源（httpx 连接池），
|
||
响应宿主生命周期状态变迁。
|
||
|
||
设计要点：
|
||
- LifecycleHandler 为单实例（非 per-account），可持有 mutable 状态用于
|
||
资源管理（与适配器的 INV-5 无 mutable 状态约束不同）。
|
||
- httpx 连接池在 ``onInit`` 创建并注入 ``ILinkClient``，``onUnload`` 解除
|
||
引用后关闭；连接数上限对齐 manifest.json 中
|
||
``resource_quota.max_connections=10``。
|
||
- 长轮询拉取由 ``StreamWorker`` 通过 ``PullerAdapter`` 统一管理，
|
||
``LifecycleHandler`` 不持有长轮询句柄。
|
||
- ``onReconfigure`` 校验不可热更新字段，变更时抛 ``ConfigRestartRequiredError``，
|
||
校验失败保持原基线以支持宿主回滚。
|
||
- ``onFail`` 不抛异常、不静默吞错；logger 失败时回退到 ``sys.stderr.write``，
|
||
不阻断 FR-36 优雅降级流程。
|
||
|
||
依赖方向：仅 import ``yuxi.channels.contract.*`` + 标准库 + httpx，
|
||
不污染框架层。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import sys
|
||
from typing import TYPE_CHECKING, Any
|
||
|
||
import httpx
|
||
|
||
from yuxi.channels.contract.dtos.config import ConfigField
|
||
from yuxi.channels.contract.errors import ConfigRestartRequiredError
|
||
from yuxi.channels.contract.ports.driven.cache_port import CachePort
|
||
from yuxi.channels.contract.ports.driven.config_port import ConfigPort
|
||
from yuxi.channels.contract.ports.driven.logger_port import LoggerPort
|
||
|
||
if TYPE_CHECKING:
|
||
from .ilink_client import ILinkClient
|
||
|
||
# httpx 连接池配置（对齐 manifest.json resource_quota: max_connections=10）
|
||
_HTTP_TIMEOUT_SECONDS = 30.0
|
||
_HTTP_MAX_CONNECTIONS = 10
|
||
_HTTP_MAX_KEEPALIVE_CONNECTIONS = 5
|
||
|
||
|
||
class WeChatILinkLifecycleHandler:
|
||
"""微信 iLink 渠道插件生命周期钩子处理。
|
||
|
||
单实例，管理插件级资源生命周期。``_http_client`` 为共享连接池，通过
|
||
``attach_http_client`` 注入 ``ILinkClient`` 供其复用（避免每请求新建
|
||
TCP 连接）；``onReconfigure`` 通过入参 ``old_config`` 做差异化校验，
|
||
不再自行维护基线缓存。长轮询连接由 ``StreamWorker`` 管理，本处理器不持有拉取句柄。
|
||
"""
|
||
|
||
def __init__(
|
||
self,
|
||
config_port: ConfigPort,
|
||
logger_port: LoggerPort,
|
||
cache_port: CachePort,
|
||
config_schema: tuple[ConfigField, ...],
|
||
client: ILinkClient | None = None,
|
||
) -> None:
|
||
self._config = config_port
|
||
self._logger = logger_port
|
||
self._cache = cache_port
|
||
self._client = client
|
||
self._http_client: httpx.AsyncClient | None = None
|
||
self._started: bool = False
|
||
# 从 config_schema 派生不可热更新键（hot_reloadable=False 的字段 key）
|
||
self._restart_required_keys: tuple[str, ...] = tuple(
|
||
field.key for field in config_schema if not field.hot_reloadable
|
||
)
|
||
|
||
# ------------------------------------------------------------------
|
||
# LifecycleHookHandler Protocol 实现
|
||
# ------------------------------------------------------------------
|
||
|
||
async def onInit(self) -> None:
|
||
"""初始化资源：创建 httpx 连接池并注入 ILinkClient。"""
|
||
self._http_client = httpx.AsyncClient(
|
||
timeout=_HTTP_TIMEOUT_SECONDS,
|
||
limits=httpx.Limits(
|
||
max_connections=_HTTP_MAX_CONNECTIONS,
|
||
max_keepalive_connections=_HTTP_MAX_KEEPALIVE_CONNECTIONS,
|
||
),
|
||
)
|
||
if self._client is not None:
|
||
self._client.attach_http_client(self._http_client)
|
||
await self._logger.info("WeChat iLink plugin initialized")
|
||
|
||
async def onStart(self) -> None:
|
||
"""标记插件就绪：允许 ILinkClient 接受新请求。"""
|
||
self._started = True
|
||
if self._client is not None:
|
||
self._client.set_active(True)
|
||
await self._logger.info("WeChat iLink plugin started")
|
||
|
||
async def onStop(self) -> None:
|
||
"""停止插件：拒绝新请求，等待在途请求完成（默认 30s 超时）。
|
||
|
||
先 ``set_active(False)`` 阻止新请求进入 ``_execute_http``，再
|
||
``drain(30)`` 等待在途请求完成。超时后记录告警但仍继续关闭流程。
|
||
"""
|
||
await self._logger.info(
|
||
"WeChat iLink plugin stopping, waiting for in-flight requests",
|
||
)
|
||
self._started = False
|
||
if self._client is not None:
|
||
self._client.set_active(False)
|
||
await self._client.drain(timeout=30.0)
|
||
|
||
async def onPause(self) -> None:
|
||
"""暂停插件：停止接收新请求。"""
|
||
self._started = False
|
||
if self._client is not None:
|
||
self._client.set_active(False)
|
||
await self._logger.info("WeChat iLink plugin paused")
|
||
|
||
async def onResume(self) -> None:
|
||
"""恢复插件：重新接收请求。"""
|
||
self._started = True
|
||
if self._client is not None:
|
||
self._client.set_active(True)
|
||
await self._logger.info("WeChat iLink plugin resumed")
|
||
|
||
async def onUnload(self) -> None:
|
||
"""释放所有资源：drain 在途请求后关闭 httpx 连接池。
|
||
|
||
长轮询连接由 ``StreamWorker`` 在宿主关停时首先停止，
|
||
本方法先 drain 在途请求（默认 30s 超时），再解除 client 引用并
|
||
关闭连接池。
|
||
"""
|
||
# 先 drain 在途请求，避免 aclose 打断正在进行的请求
|
||
if self._client is not None:
|
||
self._client.set_active(False)
|
||
await self._client.drain(timeout=30.0)
|
||
self._client.detach_http_client()
|
||
if self._http_client is not None:
|
||
try:
|
||
await self._http_client.aclose()
|
||
except Exception as exc:
|
||
await self._logger.warn(
|
||
"WeChat iLink httpx client close failed during unload",
|
||
error=str(exc),
|
||
)
|
||
self._http_client = None
|
||
|
||
self._started = False
|
||
await self._logger.info("WeChat iLink plugin unloaded")
|
||
|
||
async def onReconfigure(
|
||
self,
|
||
*,
|
||
old_config: dict[str, Any] | None = None,
|
||
new_config: dict[str, Any],
|
||
) -> None:
|
||
"""配置热更新：校验不可热更新字段。
|
||
|
||
- ``_restart_required_keys``（从 config_schema 派生，``hot_reloadable=False``
|
||
的字段）变更抛 ``ConfigRestartRequiredError``（FR-37）。
|
||
- ``old_config`` 为 ``None``（首次调用或无基线）时仅记录日志，不做对比。
|
||
- 校验失败由宿主回滚，本方法无副作用（不缓存基线，基线由宿主维护）。
|
||
"""
|
||
if old_config is None:
|
||
await self._logger.info(
|
||
"WeChat iLink plugin initial config baseline set",
|
||
)
|
||
return
|
||
|
||
for key in self._restart_required_keys:
|
||
new_value = new_config.get(key)
|
||
old_value = old_config.get(key)
|
||
if new_value != old_value:
|
||
raise ConfigRestartRequiredError(key=key) from None
|
||
|
||
await self._logger.info("WeChat iLink plugin reconfigured")
|
||
|
||
async def onFail(self, error: str) -> None:
|
||
"""失败清理：不抛异常，不阻断降级流程（FR-36）。
|
||
|
||
logger 不可用时回退到 ``sys.stderr.write``，确保失败信息不丢失、
|
||
不被静默吞掉，同时不向上抛出异常以保证降级流程继续。
|
||
"""
|
||
self._started = False
|
||
try:
|
||
await self._logger.error("WeChat iLink plugin failed", error=error)
|
||
except Exception as exc:
|
||
sys.stderr.write(f"WeChat iLink plugin failed (logger unavailable): {error}\nlogger_error={exc!r}\n")
|
||
|
||
|
||
__all__ = ["WeChatILinkLifecycleHandler"]
|