Kris
742299cb07
本次提交包含多维度代码优化与功能增强： 1. 移除报告模块冗余导入与枚举，清理报表相关代码 2. 新增扫码登录支持方法与飞书适配器适配 3. 完善异常日志与健康检查信息 4. 扩展目录、配对管理、能力查询等接口 5. 优化出站管道与事务提交后钩子逻辑 6. 修复飞书消息解析与响应空值问题 7. 重构配置更新与服务账号创建逻辑 8. 统一传输错误分类契约与错误基类扩展
141 lines
5.2 KiB
Python
141 lines
5.2 KiB
Python
"""传输层配置 DTO。
|
||
|
||
定义传输层相关的不可变值对象，包括轮询配置、流配置、传输配置、轮询结果、
|
||
流连接等。``TransportErrorCategory`` 类型定义于 ``errors.transport`` 模块，
|
||
此处通过 re-export 保持向后兼容的导入路径。所有 DTO 均为
|
||
``dataclass(frozen=True)``，仅依赖标准库，使用前向引用避免循环依赖。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from collections.abc import Awaitable, Callable
|
||
from dataclasses import dataclass
|
||
from typing import TYPE_CHECKING, Any
|
||
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
from yuxi.channels.contract.errors.transport import (
|
||
TransportErrorCategory as TransportErrorCategory,
|
||
)
|
||
|
||
if TYPE_CHECKING:
|
||
from yuxi.channels.contract.errors.transport import TransportError
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class PollingConfig:
|
||
"""轮询模式配置。
|
||
|
||
描述长轮询/短轮询的超时与批量参数配置。
|
||
|
||
模式判定规则：
|
||
- ``long_poll_timeout_ms > 0`` 且 ``poll_interval_ms == 0``：长轮询模式
|
||
- ``poll_interval_ms > 0``：短轮询模式
|
||
- 两者都为 0：未配置，由装配层在使用时校验
|
||
|
||
字段：
|
||
long_poll_timeout_ms: 长轮询超时时间（毫秒），0 表示不启用长轮询。
|
||
poll_interval_ms: 短轮询间隔时间（毫秒），0 表示不启用短轮询。
|
||
max_batch_size: 单次轮询最大拉取消息数。
|
||
"""
|
||
|
||
long_poll_timeout_ms: int = 0
|
||
poll_interval_ms: int = 0
|
||
max_batch_size: int = 100
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验轮询模式配置合法性。
|
||
|
||
``long_poll_timeout_ms`` / ``poll_interval_ms`` 必须为非负整数，
|
||
``max_batch_size`` 必须为正整数。两者同时为 0 表示未配置，由装配层
|
||
在使用时校验模式合法性（INV-8）。
|
||
"""
|
||
if self.long_poll_timeout_ms < 0:
|
||
raise ValidationError(
|
||
"long_poll_timeout_ms",
|
||
"must be a non-negative integer",
|
||
)
|
||
if self.poll_interval_ms < 0:
|
||
raise ValidationError(
|
||
"poll_interval_ms",
|
||
"must be a non-negative integer",
|
||
)
|
||
if self.max_batch_size <= 0:
|
||
raise ValidationError("max_batch_size", "must be a positive integer")
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class StreamConfig:
|
||
"""流式连接配置。
|
||
|
||
描述流式传输（如 SSE/WebSocket）的心跳与连接超时参数。
|
||
|
||
字段：
|
||
heartbeat_interval_ms: 心跳发送间隔（毫秒），用于保活检测。
|
||
connect_timeout_ms: 连接建立超时时间（毫秒）。
|
||
"""
|
||
|
||
heartbeat_interval_ms: int = 30000
|
||
connect_timeout_ms: int = 10000
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class TransportConfig:
|
||
"""传输层全局配置。
|
||
|
||
描述传输层的超时、退避重试、优雅关闭等参数，支持热更新。
|
||
配置变更时无需重启进程，传输层运行时自动应用最新值。
|
||
|
||
字段：
|
||
stall_timeout_ms: 连接空闲超时时间（毫秒），超过此时间无数据传输视为停滞。
|
||
backoff_schedule: 重试退避调度序列（秒），按重试次数依次取值，超出后使用最后一个值。
|
||
backoff_jitter: 退避时间抖动比例（0-1），用于避免惊群效应。
|
||
max_restart_attempts: 最大重启尝试次数，``None`` 表示无限重启。
|
||
graceful_shutdown_timeout_s: 优雅关闭超时时间（秒）。
|
||
"""
|
||
|
||
stall_timeout_ms: int = 120000
|
||
backoff_schedule: tuple[float, ...] = (1.0, 2.0, 5.0, 10.0, 30.0)
|
||
backoff_jitter: float = 0.2
|
||
max_restart_attempts: int | None = None
|
||
graceful_shutdown_timeout_s: float = 10.0
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class PollResult:
|
||
"""轮询结果。
|
||
|
||
描述单次轮询操作的返回结果，三种互斥状态：
|
||
1. 正常返回：``messages`` 非空或空元组，``error`` 为 ``None``，``next_cursor`` 可选
|
||
2. 错误返回：``error`` 非空，``messages`` 为空，``next_cursor`` 为 ``None``
|
||
3. 空轮询（长轮询超时）：``messages`` 为空，``error`` 为 ``None``，``next_cursor`` 保持不变
|
||
|
||
字段：
|
||
messages: 本次拉取到的消息列表（tuple 保证不可变）。
|
||
next_cursor: 下一轮询游标，``None`` 表示无更多数据。
|
||
error: 轮询过程中发生的错误，``None`` 表示成功。
|
||
"""
|
||
|
||
messages: tuple[dict[str, Any], ...] = ()
|
||
next_cursor: str | None = None
|
||
error: TransportError | None = None
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class StreamConnection:
|
||
"""流式连接句柄（P1 预留）。
|
||
|
||
封装已建立的流式连接的收发与关闭操作，用于统一 WebSocket / SSE 等
|
||
不同流式协议的接口。P1 阶段暂不实现，保留接口定义供后续扩展。
|
||
|
||
字段：
|
||
receive: 异步接收消息的回调函数。
|
||
send: 异步发送消息的回调函数。
|
||
close: 异步关闭连接的回调函数。
|
||
extra: 协议特定的扩展数据，如连接上下文、原始会话等。
|
||
"""
|
||
|
||
receive: Callable[[], Awaitable[dict[str, Any]]]
|
||
send: Callable[[dict[str, Any]], Awaitable[None]]
|
||
close: Callable[[], Awaitable[None]]
|
||
extra: Any = None
|