343 lines
14 KiB
Python
343 lines
14 KiB
Python
"""微信 wechat_woc（WechatOnCloud）渠道插件生命周期钩子处理。
|
||
|
||
实现 ``LifecycleHookHandler`` Protocol 的 8 个钩子（onInit / onStart /
|
||
onStop / onPause / onResume / onUnload / onReconfigure / onFail），
|
||
管理插件级资源（httpx 连接池）并响应宿主生命周期状态变迁。
|
||
|
||
设计要点：
|
||
- LifecycleHandler 为单实例（非 per-account），可持有 mutable 状态用于
|
||
资源管理（与适配器的 INV-5 无 mutable 状态约束不同）。
|
||
- httpx 连接池在 ``onInit`` 创建并注入 ``WocBridgeClient``，``onUnload``
|
||
解除引用后关闭；连接数上限对齐 manifest.json 中
|
||
``resource_quota.max_connections=10``。
|
||
- 短轮询拉取由 ``StreamWorker`` 通过 ``PullerAdapter`` 统一管理，
|
||
``LifecycleHandler`` 不持有轮询句柄。
|
||
- ``onReconfigure`` 校验 ``bridge_url`` 格式（必须以 ``http://`` 或
|
||
``https://`` 开头），非法时抛 ``ConfigRestartRequiredError`` 触发宿主
|
||
重启回滚（FR-37）。
|
||
- ``onUnload`` 在关闭连接池后清空 CachePort 中 ``wechat_woc:*`` 缓存，
|
||
避免插件卸载后残留孤儿缓存键（FR-32 资源释放约束）。
|
||
- ``onFail`` 不抛异常、不静默吞错；logger 失败时回退到 ``sys.stderr.write``，
|
||
不阻断 FR-36 优雅降级流程。
|
||
|
||
依赖方向：仅 import ``yuxi.channels.contract.*`` + 标准库 + httpx，
|
||
不污染框架层。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import os
|
||
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 .woc_bridge_client import WocBridgeClient
|
||
|
||
from ._constants import HTTP_TIMEOUT_SECONDS
|
||
|
||
# httpx 连接池默认配置；最终值由 discover 阶段解析的 manifest.resource_quota
|
||
# 注入，本默认值仅用于测试或未声明 resource_quota 的场景（F-03 单真相源）。
|
||
_HTTP_MAX_CONNECTIONS_DEFAULT = 10
|
||
_HTTP_MAX_KEEPALIVE_CONNECTIONS = 5
|
||
|
||
# 在途请求 drain 超时（秒），onStop/onUnload 等待在途请求完成的最长时间
|
||
_DRAIN_TIMEOUT_SECONDS = 30.0
|
||
|
||
# CachePort 失效模式（清空插件所有运行时缓存，避免孤儿键）
|
||
_CACHE_INVALIDATE_PATTERN = "wechat_woc:*"
|
||
|
||
|
||
class WeChatWocLifecycleHandler:
|
||
"""微信 wechat_woc 渠道插件生命周期钩子处理。
|
||
|
||
单实例，管理插件级资源生命周期。``_http_client`` 为共享连接池，通过
|
||
``attach_http_client`` 注入 ``WocBridgeClient`` 供其复用（避免每请求
|
||
新建 TCP 连接）；短轮询连接由 ``StreamWorker`` 管理，本处理器不持有
|
||
拉取句柄。
|
||
|
||
实现 8 个钩子（manifest.lifecycle 声明 init/start/stop/pause/resume/
|
||
unload/reconfigure/fail）。``onPause`` / ``onResume`` 通过
|
||
``set_active`` 切换 ``WocBridgeClient`` 请求接收开关，语义为"暂停
|
||
接收新请求"而非"停止拉取"——拉取 Worker 由宿主 ``StreamWorker``
|
||
在 PAUSED 状态下统一挂起，本钩子仅控制 HTTP 客户端可用性。
|
||
"""
|
||
|
||
def __init__(
|
||
self,
|
||
config_port: ConfigPort,
|
||
logger_port: LoggerPort,
|
||
cache_port: CachePort,
|
||
config_schema: tuple[ConfigField, ...],
|
||
client: WocBridgeClient | None = None,
|
||
max_connections: int = _HTTP_MAX_CONNECTIONS_DEFAULT,
|
||
) -> None:
|
||
self._config = config_port
|
||
self._logger = logger_port
|
||
self._cache = cache_port
|
||
self._client = client
|
||
self._max_connections = max_connections
|
||
self._http_client: httpx.AsyncClient | None = None
|
||
self._started: bool = False
|
||
# config_schema 保留用于未来扩展（如派生热更新键集合），当前 onReconfigure
|
||
# 仅校验 bridge_url 格式，不依赖 schema 派生键清单。
|
||
self._config_schema: tuple[ConfigField, ...] = config_schema
|
||
|
||
# ------------------------------------------------------------------
|
||
# LifecycleHookHandler Protocol 实现（8 个钩子）
|
||
# ------------------------------------------------------------------
|
||
|
||
async def onInit(self) -> None:
|
||
"""初始化资源：创建 httpx 连接池并注入 WocBridgeClient。
|
||
|
||
超时 60s（由宿主控制），超时后标记插件失败。
|
||
|
||
@pre
|
||
- 宿主已注入 ConfigPort / LoggerPort / CachePort
|
||
- ``client``（若提供）尚未持有 httpx 连接池
|
||
|
||
@post
|
||
- ``_http_client`` 已创建并注入 ``WocBridgeClient``（若提供）
|
||
- 后续 HTTP 请求复用该连接池
|
||
|
||
@failure
|
||
- 无（httpx.AsyncClient 构造失败由宿主捕获并触发 onFail）
|
||
|
||
@consistency
|
||
- 状态机驱动：钩子完成后状态机推进至 INITIALIZED
|
||
"""
|
||
timeout_seconds = _read_http_timeout()
|
||
self._http_client = httpx.AsyncClient(
|
||
timeout=timeout_seconds,
|
||
limits=httpx.Limits(
|
||
max_connections=self._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 woc plugin initialized")
|
||
|
||
async def onStart(self) -> None:
|
||
"""标记插件就绪：允许 WocBridgeClient 接受新请求。
|
||
|
||
超时 60s（由宿主控制）。
|
||
|
||
@post
|
||
- ``_started=True``
|
||
- ``WocBridgeClient.set_active(True)`` 已调用
|
||
|
||
@consistency
|
||
- 状态机驱动：钩子完成后状态机推进至 STARTED
|
||
"""
|
||
self._started = True
|
||
if self._client is not None:
|
||
self._client.set_active(True)
|
||
await self._logger.info("WeChat woc plugin started")
|
||
|
||
async def onStop(self) -> None:
|
||
"""停止插件：拒绝新请求，等待在途请求完成（默认 30s 超时）。
|
||
|
||
先 ``set_active(False)`` 阻止新请求进入 ``_execute_http``，再
|
||
``drain(30)`` 等待在途请求完成。超时后记录告警但仍继续关闭流程。
|
||
|
||
@post
|
||
- ``_started=False``
|
||
- ``WocBridgeClient.set_active(False)`` 已调用
|
||
- 在途请求已 drain（超时则告警，不抛异常）
|
||
|
||
@consistency
|
||
- 状态机驱动：钩子完成后状态机推进至 STOPPED
|
||
- 幂等：停止已停止的插件安全
|
||
"""
|
||
await self._logger.info(
|
||
"WeChat woc 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=_DRAIN_TIMEOUT_SECONDS)
|
||
|
||
async def onPause(self) -> None:
|
||
"""暂停插件：停止接收新请求，但在途请求继续完成。
|
||
|
||
与 ``onStop`` 的区别：不 drain 在途请求，仅 ``set_active(False)``
|
||
阻止新请求进入 ``_execute_http``，已接收的请求继续执行至完成。
|
||
适用于宿主临时挂起场景（如配置预校验、限流降级），恢复后调用
|
||
``onResume`` 即可重新接收请求。
|
||
|
||
@post
|
||
- ``_started=False``
|
||
- ``WocBridgeClient.set_active(False)`` 已调用
|
||
|
||
@consistency
|
||
- 状态机驱动：钩子完成后状态机推进至 PAUSED
|
||
- 幂等：暂停已暂停的插件安全
|
||
"""
|
||
self._started = False
|
||
if self._client is not None:
|
||
self._client.set_active(False)
|
||
await self._logger.info("WeChat woc plugin paused")
|
||
|
||
async def onResume(self) -> None:
|
||
"""恢复插件：重新接收新请求。
|
||
|
||
仅在 PAUSED 状态下由宿主调用，恢复 ``WocBridgeClient`` 请求接收
|
||
开关。若插件未启动（``_http_client`` 为 None），仅标记 ``_started``
|
||
等待 ``onStart`` 完成资源装配。
|
||
|
||
@pre
|
||
- 插件处于 PAUSED 状态
|
||
|
||
@post
|
||
- ``_started=True``
|
||
- ``WocBridgeClient.set_active(True)`` 已调用（若 client 存在）
|
||
|
||
@consistency
|
||
- 状态机驱动：钩子完成后状态机推进至 STARTED
|
||
- 幂等：恢复已启动的插件安全
|
||
"""
|
||
self._started = True
|
||
if self._client is not None:
|
||
self._client.set_active(True)
|
||
await self._logger.info("WeChat woc plugin resumed")
|
||
|
||
async def onUnload(self) -> None:
|
||
"""释放所有资源：drain 在途请求后关闭 httpx 连接池并清空缓存。
|
||
|
||
超时 30s（由宿主控制），必须释放所有资源，不得留下孤儿资源
|
||
（FR-32 资源释放约束）。
|
||
|
||
步骤：
|
||
1. ``set_active(False)`` + ``drain(30)`` 等待在途请求完成
|
||
2. ``detach_http_client`` 解除 client 引用（避免悬挂）
|
||
3. ``aclose()`` 关闭连接池（异常告警不抛）
|
||
4. ``cache_port.invalidate("wechat_woc:*")`` 清空插件运行时缓存
|
||
（异常告警不抛，遵循 CachePort 写故障降级约定）
|
||
|
||
@post
|
||
- ``_http_client=None``、``_started=False``
|
||
- CachePort 中 ``wechat_woc:*`` 模式缓存已失效
|
||
|
||
@consistency
|
||
- 状态机驱动：钩子完成后状态机推进至 UNLOADED
|
||
- 幂等：重复卸载仅清理已释放的资源
|
||
"""
|
||
# 1. 先 drain 在途请求，避免 aclose 打断正在进行的请求
|
||
if self._client is not None:
|
||
self._client.set_active(False)
|
||
await self._client.drain(timeout=_DRAIN_TIMEOUT_SECONDS)
|
||
self._client.detach_http_client()
|
||
# 2. 关闭 httpx 连接池（异常告警不抛，避免阻断后续缓存清理）
|
||
if self._http_client is not None:
|
||
try:
|
||
await self._http_client.aclose()
|
||
except Exception as exc:
|
||
await self._logger.warn(
|
||
"WeChat woc httpx client close failed during unload",
|
||
error=str(exc),
|
||
)
|
||
self._http_client = None
|
||
|
||
# 3. 清空 CachePort 中 wechat_woc:* 缓存，避免孤儿键残留
|
||
try:
|
||
await self._cache.invalidate(pattern=_CACHE_INVALIDATE_PATTERN)
|
||
except Exception as exc:
|
||
await self._logger.warn(
|
||
"WeChat woc cache invalidate failed during unload",
|
||
error=str(exc),
|
||
)
|
||
|
||
self._started = False
|
||
await self._logger.info("WeChat woc plugin unloaded")
|
||
|
||
async def onReconfigure(
|
||
self,
|
||
*,
|
||
old_config: dict[str, Any] | None = None,
|
||
new_config: dict[str, Any],
|
||
) -> None:
|
||
"""配置热更新：校验 bridge_url 格式，非法抛 ConfigRestartRequiredError。
|
||
|
||
``bridge_url`` 为 wechat_woc 唯一不可降级校验的配置项：必须以
|
||
``http://`` 或 ``https://`` 开头，否则视为配置非法，抛
|
||
``ConfigRestartRequiredError`` 触发宿主重启回滚（FR-37）。
|
||
|
||
校验通过后仅记录日志，不缓存基线（wechat_woc 的 bridge_url 实时
|
||
从 ConfigPort 读取，无需本地缓存）。``old_config`` 由宿主通过关键字
|
||
参数传入，wechat_woc 仅做格式校验、无差异化校验需求，故不消费。
|
||
|
||
@pre
|
||
- ``new_config`` 为新配置字典，含 ``bridge_url`` 字段
|
||
|
||
@post
|
||
- 校验通过：日志记录，配置即时生效（bridge_url 实时读取）
|
||
- 校验失败：抛 ``ConfigRestartRequiredError``，宿主回滚
|
||
|
||
@failure
|
||
- ``ConfigRestartRequiredError``：``bridge_url`` 格式非法
|
||
|
||
@consistency
|
||
- 状态机驱动：配置变更即时生效且支持回滚
|
||
- 幂等：相同配置重复应用产生等价结果
|
||
"""
|
||
bridge_url = new_config.get("bridge_url")
|
||
if not isinstance(bridge_url, str) or not bridge_url:
|
||
raise ConfigRestartRequiredError(key="bridge_url") from None
|
||
if not (bridge_url.startswith("http://") or bridge_url.startswith("https://")):
|
||
raise ConfigRestartRequiredError(key="bridge_url") from None
|
||
await self._logger.info("WeChat woc plugin reconfigured")
|
||
|
||
async def onFail(self, error: str) -> None:
|
||
"""失败清理：不抛异常，不阻断降级流程（FR-36）。
|
||
|
||
插件初始化/启动/运行时失败时由宿主调用，标记 ``_started=False``
|
||
并记录错误日志。logger 不可用时回退到 ``sys.stderr.write``，确保
|
||
失败信息不丢失、不被静默吞掉，同时不向上抛出异常以保证降级流程
|
||
继续。
|
||
|
||
@post
|
||
- ``_started=False``
|
||
- 错误已记录（logger 或 stderr 兜底）
|
||
- 不抛出任何异常
|
||
|
||
@consistency
|
||
- 状态机驱动：钩子完成后状态机推进至 FAILED 并触发降级
|
||
- 幂等：重复通知失败仅记录状态，无累积副作用
|
||
"""
|
||
self._started = False
|
||
try:
|
||
await self._logger.error("WeChat woc plugin failed", error=error)
|
||
except Exception as exc:
|
||
sys.stderr.write(f"WeChat woc plugin failed (logger unavailable): {error}\nlogger_error={exc!r}\n")
|
||
|
||
|
||
def _read_http_timeout() -> float:
|
||
"""读取 HTTP 客户端超时（秒）。
|
||
|
||
优先读取环境变量 ``WOC_HTTP_TIMEOUT_MS``（与 manifest.json env_vars 声明
|
||
对齐），解析为秒；未设置或解析失败时回退到 ``HTTP_TIMEOUT_SECONDS``。
|
||
|
||
Returns:
|
||
HTTP 超时秒数（>=1.0）。
|
||
"""
|
||
env_value = os.environ.get("WOC_HTTP_TIMEOUT_MS")
|
||
if env_value:
|
||
try:
|
||
ms = int(env_value)
|
||
if ms >= 1000:
|
||
return ms / 1000.0
|
||
except (ValueError, TypeError):
|
||
pass
|
||
return HTTP_TIMEOUT_SECONDS
|
||
|
||
|
||
__all__ = ["WeChatWocLifecycleHandler"]
|