Kris
8eead29de0
1. 移除所有适配器文件中多余的空导入行 2. 调整ValidationError继承，移除不必要的ValueError继承 3. 修正多处ChannelType使用方式，从.value改为直接使用枚举实例 4. 优化飞书插件部分硬编码渠道类型为枚举实例 5. 更新wechat_ilink插件清单与适配器配置 6. 新增飞书目录适配器缓存清理支持判断与iLink生命周期适配器凭据轮换支持判断 7. 优化配置处理器历史查询逻辑，区分键不存在与无历史记录场景
189 lines
7.8 KiB
Python
189 lines
7.8 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 连接）；``_last_config`` 缓存上一次有效配置，供 ``onReconfigure``
|
||
校验与回滚。长轮询连接由 ``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
|
||
self._last_config: dict[str, Any] | None = None
|
||
# 从 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, config: dict[str, Any]) -> None:
|
||
"""配置热更新：校验不可热更新字段，接受则缓存为新基线。
|
||
|
||
- ``_restart_required_keys``（从 config_schema 派生，``hot_reloadable=False``
|
||
的字段）变更抛 ``ConfigRestartRequiredError``（FR-37）。
|
||
- 首次调用（``_last_config`` 为 None）仅建立基线，不做对比。
|
||
- 校验通过后更新 ``_last_config``；校验失败保持原基线，由宿主回滚。
|
||
"""
|
||
if self._last_config is None:
|
||
self._last_config = dict(config)
|
||
await self._logger.info(
|
||
"WeChat iLink plugin initial config baseline set",
|
||
)
|
||
return
|
||
|
||
for key in self._restart_required_keys:
|
||
new_value = config.get(key)
|
||
old_value = self._last_config.get(key)
|
||
if new_value != old_value:
|
||
raise ConfigRestartRequiredError(key=key) from None
|
||
|
||
self._last_config = dict(config)
|
||
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"]
|