72 lines
2.2 KiB
Python
72 lines
2.2 KiB
Python
"""多渠道网关异常基类。
|
||
|
||
插件在投递、校验或降级过程中应优先抛出这些异常，便于调度器区分
|
||
永久失败（应停止重试并标记死信）与可重试失败（应指数退避后重试）。
|
||
"""
|
||
|
||
from enum import StrEnum
|
||
|
||
|
||
class ChannelErrorClassification(StrEnum):
|
||
"""插件对投递异常的分类结果，供调度器决定重试策略。"""
|
||
|
||
RETRYABLE = "retryable" # 网络抖动、服务端 5xx、未明确分类的瞬态故障
|
||
PERMANENT = "permanent" # 配置错误、凭证失效、用户被拉黑、内容永久拒绝
|
||
RATE_LIMITED = "rate_limited" # 明确限流，可配合 retry_after 退避
|
||
|
||
|
||
class ChannelError(Exception):
|
||
"""渠道网关相关异常的基类。"""
|
||
|
||
|
||
class ChannelPermanentError(ChannelError):
|
||
"""渠道侧永久错误，不应重试。
|
||
|
||
例如：凭证失效、会话不存在、消息内容被渠道永久拒绝、用户已拉黑机器人等。
|
||
"""
|
||
|
||
|
||
class ChannelValidationError(ChannelPermanentError):
|
||
"""入站/出站消息格式或签名校验失败。
|
||
|
||
属于永久失败，重复投递无法自动修复。
|
||
"""
|
||
|
||
|
||
class ChannelRetryableError(ChannelError):
|
||
"""渠道侧可重试错误。
|
||
|
||
例如：网络超时、渠道服务端 5xx、限流（429）等瞬态故障。
|
||
"""
|
||
|
||
|
||
class ChannelRateLimitedError(ChannelRetryableError):
|
||
"""渠道侧明确限流错误。
|
||
|
||
可配合 retry_after 进行退避；未提供时由调度器使用默认指数退避。
|
||
"""
|
||
|
||
def __init__(self, *args: object, retry_after: int | None = None) -> None:
|
||
super().__init__(*args)
|
||
self.retry_after = retry_after
|
||
|
||
|
||
class ChannelConfigurationError(ChannelPermanentError):
|
||
"""渠道配置缺失或非法导致的永久失败。"""
|
||
|
||
|
||
class ChannelNotSupportedError(ChannelPermanentError):
|
||
"""当前渠道不支持某种消息类型或能力。"""
|
||
|
||
|
||
class ChannelTransportReconnectRequested(ChannelError):
|
||
"""插件请求传输层立即断开并重连。
|
||
|
||
例如 Slack Socket Mode 收到 disconnect 信封后，需要主动断开当前连接
|
||
并让生命周期管理器重新建立连接。
|
||
"""
|
||
|
||
|
||
class ChannelNotLoggedInError(ChannelError):
|
||
"""未登录时调用需要登录状态的操作（如发送消息）。"""
|