Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
139 lines
5.1 KiB
Python
139 lines
5.1 KiB
Python
"""传输层配置 DTO。
|
||
|
||
定义传输层相关的不可变值对象，包括轮询配置、流配置、传输配置、轮询结果、
|
||
流连接等，以及传输错误分类类型。所有 DTO 均为 ``dataclass(frozen=True)``，
|
||
仅依赖标准库，使用前向引用避免循环依赖。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from collections.abc import Awaitable, Callable
|
||
from dataclasses import dataclass
|
||
from typing import TYPE_CHECKING, Any, Literal
|
||
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
|
||
if TYPE_CHECKING:
|
||
from yuxi.channels.contract.errors.transport import TransportError
|
||
|
||
TransportErrorCategory = Literal["auth_expired", "rate_limited", "transient", "permanent"]
|
||
|
||
|
||
@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
|