Kris
c88afb79ce
实现钉钉企业机器人全渠道能力，包含会话解析、消息收发、富消息卡片、命令适配、身份解析、状态回传、健康探测等功能，提供完整的Stream/HTTP双模式事件接入支持，遵循单真相源设计原则，以manifest.json作为配置唯一依据。
179 lines
7.1 KiB
Python
179 lines
7.1 KiB
Python
"""钉钉渠道插件生命周期钩子处理。
|
||
|
||
实现 ``LifecycleHookHandler`` Protocol，管理插件级资源（httpx 连接池），
|
||
响应宿主生命周期状态变迁。
|
||
|
||
设计要点：
|
||
- LifecycleHandler 为单实例（非 per-account），可持有 mutable 状态用于
|
||
资源管理（与适配器的 INV-5 无 mutable 状态约束不同）。
|
||
- httpx 连接池在 ``onInit`` 创建并注入 ``DingTalkClient``，``onUnload``
|
||
解除引用后关闭；连接数上限对齐 manifest.json 中
|
||
``resource_quota.max_connections=50``。
|
||
- Stream 模式 WS 长连接由 ``StreamWorker`` 通过
|
||
``DingTalkStreamConnectorAdapter`` 统一管理，``LifecycleHandler`` 不持有
|
||
WS 客户端句柄（设计方案 §2.4.4）。
|
||
- ``onReconfigure`` 从配置 schema 派生不可热更新键列表
|
||
（``hot_reloadable=False``），变更时抛 ``ConfigRestartRequiredError``。
|
||
``config_schema`` 为必填，不再有硬编码回退清单（避免与 manifest 不一致）。
|
||
- ``onFail`` 不抛异常，不阻断降级流程；logger 不可用时回退 ``stderr``。
|
||
|
||
依赖方向：仅 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
|
||
|
||
from ._constants import (
|
||
HTTP_MAX_CONNECTIONS,
|
||
HTTP_MAX_KEEPALIVE_CONNECTIONS,
|
||
HTTP_TIMEOUT_SECONDS,
|
||
)
|
||
|
||
if TYPE_CHECKING:
|
||
from .dingtalk_client import DingTalkClient
|
||
|
||
|
||
class DingTalkLifecycleHandler:
|
||
"""钉钉渠道插件生命周期钩子处理。
|
||
|
||
单实例，管理插件级资源生命周期。``_http_client`` 为共享连接池，通过
|
||
``attach_http_client`` 注入 ``DingTalkClient`` 供其复用（避免每请求新建
|
||
TCP 连接）；``onReconfigure`` 通过入参 ``old_config`` 做差异化校验，
|
||
不再自行维护基线缓存。不可热更新键列表从配置 schema 派生
|
||
（``hot_reloadable=False``），``config_schema`` 必填。Stream 连接由
|
||
``StreamWorker`` 管理，本处理器不持有 WS 句柄。
|
||
"""
|
||
|
||
def __init__(
|
||
self,
|
||
config_port: ConfigPort,
|
||
logger_port: LoggerPort,
|
||
cache_port: CachePort,
|
||
config_schema: tuple[ConfigField, ...],
|
||
client: DingTalkClient | 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），
|
||
# 不再硬编码回退清单以避免与 manifest config_schema 不一致
|
||
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 连接池并注入 DingTalkClient。"""
|
||
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("DingTalk plugin initialized")
|
||
|
||
async def onStart(self) -> None:
|
||
"""标记插件就绪。"""
|
||
self._started = True
|
||
await self._logger.info("DingTalk plugin started")
|
||
|
||
async def onStop(self) -> None:
|
||
"""停止插件：标记未就绪，等待在途请求完成。"""
|
||
await self._logger.info(
|
||
"DingTalk plugin stopping, waiting for in-flight requests",
|
||
)
|
||
self._started = False
|
||
|
||
async def onPause(self) -> None:
|
||
"""暂停插件：停止接收新请求。"""
|
||
self._started = False
|
||
await self._logger.info("DingTalk plugin paused")
|
||
|
||
async def onResume(self) -> None:
|
||
"""恢复插件：重新接收请求。"""
|
||
self._started = True
|
||
await self._logger.info("DingTalk plugin resumed")
|
||
|
||
async def onUnload(self) -> None:
|
||
"""释放所有资源：解除 DingTalkClient 引用后关闭 httpx 连接池。
|
||
|
||
Stream WS 连接由 ``TransportManager.stop()`` 在宿主关停时首先关闭，
|
||
本方法不再处理 WS 客户端清理。先 ``detach_http_client`` 解除 client
|
||
引用（避免悬挂），再 ``aclose`` 关闭连接池。
|
||
"""
|
||
if self._client is not None:
|
||
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(
|
||
"DingTalk httpx client close failed during unload",
|
||
error=str(exc),
|
||
)
|
||
self._http_client = None
|
||
|
||
self._started = False
|
||
await self._logger.info("DingTalk plugin unloaded")
|
||
|
||
async def onReconfigure(
|
||
self,
|
||
*,
|
||
old_config: dict[str, Any] | None = None,
|
||
new_config: dict[str, Any],
|
||
) -> None:
|
||
"""配置热更新：校验不可热更新字段。
|
||
|
||
- 不可热更新键（``hot_reloadable=False``，如 ``client_id`` /
|
||
``client_secret`` / ``robot_code`` / ``event_mode``）变更抛
|
||
``ConfigRestartRequiredError``（FR-37）。
|
||
- ``old_config`` 为 ``None``（首次调用或无基线）时仅记录日志，不做对比。
|
||
- 校验失败由宿主回滚，本方法无副作用（不缓存基线，基线由宿主维护）。
|
||
"""
|
||
if old_config is None:
|
||
await self._logger.info("DingTalk 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("DingTalk plugin reconfigured")
|
||
|
||
async def onFail(self, error: str) -> None:
|
||
"""失败清理：不抛异常，不阻断降级流程（FR-36）。
|
||
|
||
logger 不可用时回退 ``sys.stderr.write``，确保失败信息不丢失。
|
||
不抛异常以遵守 FR-36「不阻断降级流程」约束。
|
||
"""
|
||
self._started = False
|
||
try:
|
||
await self._logger.error("DingTalk plugin failed", error=error)
|
||
except Exception as exc:
|
||
sys.stderr.write(f"DingTalk plugin failed: {error}\nLogger error: {exc}\n")
|
||
|
||
|
||
__all__ = ["DingTalkLifecycleHandler"]
|