refactor(error): 重构错误处理机制，改进核心模块和 TUI 模块的结果类型

Author: KercyDing

.github/workflows/check.yml

@@ -27,8 +27,6 @@ jobs:
 
       - run: cargo build --workspace --bins
 
-      - run: cargo clippy --workspace -- -D warnings
-
-      - run: cargo clippy -p sculk-tui --no-deps -- -D warnings -W clippy::unwrap_used -W clippy::expect_used -W clippy::panic
+      - run: cargo clippy --workspace --all-targets --all-features
 
       - run: cargo test --workspace --features sculk/ci

Cargo.lock

@@ -24,3 +24,9 @@ rand = "0.10"
 serde = { version = "1", features = ["derive"] }
 toml = "1"
 url = "2.5"
+thiserror = "2"
+
+[workspace.lints.clippy]
+unwrap_used = "deny"
+expect_used = "deny"
+panic = "deny"

Cargo.toml

@@ -30,7 +30,7 @@ uninstall-all: uninstall uninstall-tui
 check:
     cargo fmt --all -- --check
     cargo check --workspace
-    cargo clippy --workspace -- -D warnings
+    cargo clippy --workspace --all-targets --all-features
 
 # 离线测试
 test:

Justfile

@@ -24,3 +24,6 @@ tracing-subscriber.workspace = true
 [[bin]]
 name = "sckc"
 path = "src/main.rs"
+
+[lints]
+workspace = true

cli/Cargo.toml

@@ -115,7 +115,10 @@ async fn run_command(cli: Cli) -> anyhow::Result<()> {
             password,
             max_players,
         } => {
-            let path = key_path.unwrap_or_else(persist::default_key_path);
+            let path = match key_path {
+                Some(path) => path,
+                None => persist::default_key_path()?,
+            };
             let secret_key = if new_key {
                 persist::generate_new_key(&path)?
             } else {
@@ -220,11 +223,11 @@ async fn run_command(cli: Cli) -> anyhow::Result<()> {
                     println!("Using default n0 relay servers.");
                 }
             } else {
-                Cli::command()
+                let mut relay_subcommand = Cli::command()
                     .find_subcommand("relay")
-                    .expect("relay subcommand should exist")
-                    .clone()
-                    .print_help()?;
+                    .ok_or_else(|| anyhow::anyhow!("relay subcommand should exist"))?
+                    .clone();
+                relay_subcommand.print_help()?;
             }
         }
     }
@@ -266,13 +269,17 @@ mod tests {
 
     #[test]
     fn parse_host_command_from_args() {
-        let cli = Cli::try_parse_from(["sculk", "host", "-p", "25565"]).expect("parse host");
+        let cli_res = Cli::try_parse_from(["sckc", "host", "-p", "25565"]);
+        assert!(cli_res.is_ok(), "parse host");
+        let cli = if let Ok(v) = cli_res { v } else { return };
         assert!(matches!(cli.command, Commands::Host { port: 25565, .. }));
     }
 
     #[test]
     fn parse_join_defaults() {
-        let cli = Cli::try_parse_from(["sculk", "join", "ticket"]).expect("parse join");
+        let cli_res = Cli::try_parse_from(["sckc", "join", "ticket"]);
+        assert!(cli_res.is_ok(), "parse join");
+        let cli = if let Ok(v) = cli_res { v } else { return };
         assert!(
             matches!(cli.command, Commands::Join { port, .. } if port == sculk::DEFAULT_INLET_PORT)
         );

cli/src/main.rs

@@ -0,0 +1,3 @@
+allow-unwrap-in-tests = false
+allow-expect-in-tests = false
+allow-panic-in-tests = false

clippy.toml

@@ -20,11 +20,11 @@ clipboard = ["dep:arboard"]
 persist = ["dep:dirs", "dep:rand", "dep:serde", "dep:toml"]
 
 [dependencies]
-anyhow.workspace = true
 iroh.workspace = true
 tokio.workspace = true
 tracing.workspace = true
 url.workspace = true
+thiserror.workspace = true
 arboard = { workspace = true, optional = true }
 dirs = { workspace = true, optional = true }
 rand = { workspace = true, optional = true }
@@ -33,3 +33,6 @@ toml = { workspace = true, optional = true }
 
 [dev-dependencies]
 rand.workspace = true
+
+[lints]
+workspace = true

core/Cargo.toml

@@ -0,0 +1,151 @@
+//! core crate 统一错误类型。
+
+use std::path::PathBuf;
+
+use thiserror::Error;
+
+/// 持久化层错误。
+#[derive(Debug, Error)]
+pub enum PersistError {
+    /// 系统数据目录不可用。
+    #[error("cannot determine system data directory")]
+    SystemDataDirUnavailable,
+    /// 路径 I/O 错误。
+    #[error("{op} `{path}` failed: {source}")]
+    PathIo {
+        op: &'static str,
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+    /// 密钥文件长度非法。
+    #[error("invalid key file length: expected {expected} bytes, got {actual} bytes")]
+    InvalidKeyLength { expected: usize, actual: usize },
+    /// profile 解析失败。
+    #[cfg(feature = "persist")]
+    #[error("failed to parse profile `{path}`: {source}")]
+    ProfileParse {
+        path: PathBuf,
+        #[source]
+        source: toml::de::Error,
+    },
+    /// profile 序列化失败。
+    #[cfg(feature = "persist")]
+    #[error(transparent)]
+    ProfileSerialize(#[from] toml::ser::Error),
+    /// relay URL 解析失败。
+    #[error("invalid relay URL: {0}")]
+    RelayUrlParse(String),
+}
+
+/// 票据解析错误。
+#[derive(Debug, Error)]
+pub enum TicketError {
+    /// URL 解析失败。
+    #[error(transparent)]
+    UrlParse(#[from] url::ParseError),
+    /// 协议不匹配。
+    #[error("invalid scheme: expected \"{expected}\", got \"{actual}\"")]
+    InvalidScheme {
+        expected: &'static str,
+        actual: String,
+    },
+    /// 缺少 endpoint id。
+    #[error("missing endpoint id in ticket URL")]
+    MissingEndpointId,
+    /// endpoint id 非法。
+    #[error("invalid endpoint id: {0}")]
+    EndpointIdParse(String),
+    /// relay URL 非法。
+    #[error("invalid relay URL: {0}")]
+    RelayUrlParse(String),
+}
+
+/// 隧道运行时错误。
+#[derive(Debug, Error)]
+pub enum TunnelError {
+    /// 锁中毒。
+    #[error("mutex poisoned: {name}")]
+    MutexPoisoned { name: &'static str },
+    /// 绑定 host endpoint 失败。
+    #[error("bind host endpoint failed: {0}")]
+    BindHostEndpoint(String),
+    /// 绑定 join endpoint 失败。
+    #[error("bind join endpoint failed: {0}")]
+    BindJoinEndpoint(String),
+    /// 绑定本地 TCP 监听失败。
+    #[error("bind local tcp listener failed: {0}")]
+    BindLocalListener(String),
+    /// host accept 失败。
+    #[error("accept host connection failed: {0}")]
+    AcceptHostConnection(String),
+    /// QUIC 双向流 accept 失败。
+    #[error("accept QUIC bi stream failed: {0}")]
+    AcceptQuicBiStream(String),
+    /// 本地 TCP 客户端 accept 失败。
+    #[error("accept local tcp client failed: {0}")]
+    AcceptLocalTcpClient(String),
+    /// 与 host 建连失败。
+    #[error("connect host endpoint failed: {0}")]
+    ConnectHostEndpoint(String),
+    /// 初次连接重试耗尽。
+    #[error("initial connection failed after {attempts} attempts")]
+    InitialConnectionExhausted { attempts: u32 },
+    /// 打开认证流失败。
+    #[error("open auth stream failed: {0}")]
+    OpenAuthStream(String),
+    /// 接收认证流失败。
+    #[error("accept auth stream failed: {0}")]
+    AcceptAuthStream(String),
+    /// 读取认证结果失败。
+    #[error("read auth result failed: {0}")]
+    ReadAuthResult(String),
+    /// 读取认证负载失败。
+    #[error("read auth payload failed: {0}")]
+    ReadAuthPayload(String),
+    /// 写入认证负载失败。
+    #[error("write auth payload failed: {0}")]
+    WriteAuthPayload(String),
+    /// 写入认证拒绝失败。
+    #[error("write auth rejected failed: {0}")]
+    WriteAuthRejected(String),
+    /// 写入认证决策失败。
+    #[error("write auth decision failed: {0}")]
+    WriteAuthDecision(String),
+    /// 结束认证流失败。
+    #[error("finish auth stream failed: {0}")]
+    FinishAuthStream(String),
+    /// 认证被 host 拒绝。
+    #[error("auth rejected by host")]
+    AuthRejectedByHost,
+    /// 桥接 tcp->quic 失败。
+    #[error("bridge tcp->quic failed: {0}")]
+    BridgeTcpToQuic(String),
+    /// 桥接 quic->tcp 失败。
+    #[error("bridge quic->tcp failed: {0}")]
+    BridgeQuicToTcp(String),
+}
+
+/// sculk core 顶层错误。
+#[derive(Debug, Error)]
+pub enum SculkError {
+    /// 持久化错误。
+    #[error(transparent)]
+    Persist(#[from] PersistError),
+    /// 票据错误。
+    #[error(transparent)]
+    Ticket(#[from] TicketError),
+    /// 隧道错误。
+    #[error(transparent)]
+    Tunnel(#[from] TunnelError),
+}
+
+impl TunnelError {
+    /// 构造锁中毒错误。
+    pub fn mutex_poisoned(name: &'static str) -> Self {
+        Self::MutexPoisoned { name }
+    }
+}
+
+/// core crate 统一 `Result` 别名。
+pub type Result<T> = std::result::Result<T, SculkError>;

core/src/error.rs

@@ -17,7 +17,7 @@
 //! ```no_run
 //! use sculk::tunnel::{IrohTunnel, TunnelConfig};
 //!
-//! # async fn demo() -> anyhow::Result<()> {
+//! # async fn demo() -> sculk::Result<()> {
 //! let (_tunnel, ticket, mut events) =
 //!     IrohTunnel::host(25565, None, None, TunnelConfig::default()).await?;
 //! println!("share ticket: {ticket}");
@@ -34,7 +34,7 @@
 //! ```no_run
 //! use sculk::tunnel::{IrohTunnel, Ticket, TunnelConfig};
 //!
-//! # async fn demo() -> anyhow::Result<()> {
+//! # async fn demo() -> sculk::Result<()> {
 //! let ticket: Ticket = "sculk://<endpoint-id>".parse()?;
 //! let (_tunnel, mut events) = IrohTunnel::join(&ticket, 30000, TunnelConfig::default()).await?;
 //!
@@ -53,10 +53,13 @@
 
 #[cfg(feature = "clipboard")]
 pub mod clipboard;
+pub mod error;
 #[cfg(feature = "persist")]
 pub mod persist;
 pub mod tunnel;
 
+pub use error::{Result, SculkError};
+
 /// Minecraft 服务端标准端口。
 pub const DEFAULT_MC_PORT: u16 = 25565;