Kris
b88c0ae29e
新增完整的 channels 限界上下文模块，包含契约层、领域核心层、应用服务、管道编排、插件体系、基础设施组合根等全层级代码，新增飞书与微信 iLink 渠道插件基础结构，补充各类 DTO、端口协议与领域服务实现。
113 lines
4.1 KiB
Python
113 lines
4.1 KiB
Python
"""传输层配置 DTO。
|
||
|
||
定义传输层相关的不可变值对象，包括轮询配置、流配置、传输配置、轮询结果、
|
||
流连接等，以及传输错误分类类型。所有 DTO 均为 ``dataclass(frozen=True)``，
|
||
仅依赖标准库，使用前向引用避免循环依赖。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from typing import Any, Awaitable, Callable, Literal
|
||
|
||
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
|
||
|
||
|
||
@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
|