//! df-tunnel 错误类型
//!
//! 设计:单一 TunnelError 覆盖 WS 连接/收发/序列化/鉴权四类失败,
//! thiserror 派生保留错误链(`#[from]` 自动 From)。
//! 脚手架阶段仅定义类型,不涉及具体错误码细分(Phase2 填充)。

use thiserror::Error;

/// 隧道客户端运行期错误
///
/// 覆盖范围:
/// - 连接建立失败(网络不可达 / TLS 握手 / 鉴权拒绝)
/// - 收发失败(底层 WS 帧 / 序列化 / 反序列化)
/// - 协议层错误(未预期的消息类型 / 配对绑定失败)
#[derive(Debug, Error)]
pub enum TunnelError {
    /// WS 连接建立或断线重连失败
    #[error("隧道连接失败: {0}")]
    Connect(String),

    /// 底层 tungstenite WS 协议错误
    #[error("WS 协议错误: {0}")]
    WebSocket(#[from] tokio_tungstenite::tungstenite::Error),

    /// 消息序列化/反序列化失败
    #[error("消息序列化失败: {0}")]
    Serde(#[from] serde_json::Error),

    /// 云后端鉴权/配对拒绝(token 无效 / device 未绑定)
    #[error("鉴权/配对失败: {0}")]
    Auth(String),

    /// 隧道未连接(对 send/recv 的前置状态校验失败)
    #[error("隧道未连接")]
    NotConnected,

    /// 其他未归类错误(降级通道,Phase2 视需要细分)
    #[error("隧道内部错误: {0}")]
    Other(#[from] anyhow::Error),
}

/// 模块级 Result 别名,简化调用方签名
pub type Result<T> = std::result::Result<T, TunnelError>;