Errors and Timeouts

English · 简体中文

错误、超时与取消

传输错误

rust_raknet::error::Result<T> 使用 RaknetError，实现 Display 和 std::error::Error。完整枚举如下：

枚举	排查方向／含义
SetRaknetRawSocketError	传入 UDP socket 初始化失败
NotListen	accept 前先调用 listen
BindAddressError	检查地址、端口占用和 socket 权限
ConnectionClosed	会话已结束，按应用策略重新连接
NotSupportVersion	检查 RakNet 握手版本，通常为 10 或 11
IncorrectReply	检查对端传输方式、地址和握手响应
PacketParseError	检查不合法或不兼容的对端包
SocketError	检查 socket 操作和调优参数；该枚举不保留底层 OS errno
IncorrectReliability	检查可靠性字段和支持的模式
IncorrectPacketID	检查控制包或应用包标识
ReadPacketBufferError	检查截断的输入包
PacketSizeExceedMTU	检查模式、MTU、分片数和编码字节预算
PacketHeaderError	发送非空且首字节为 0xfe 的消息
SetMotdError	检查离线 MOTD 更新和监听器状态

这些错误不是网络故障的完整诊断，超时或解析失败不能单独证明协议不兼容，应核对两端日志和脱敏抓包。

应用超时

异步接口并非每个操作都有 timeout 变体。需要截止时间时，用 tokio::time::timeout 包装 connect、recv、send、flush 或 accept。外层错误是 Tokio Elapsed，内层是传输结果。

use rust_raknet::RaknetSocket;
use std::time::Duration;

async fn receive_with_deadline(socket: &RaknetSocket)
    -> Result<Vec<u8>, Box<dyn std::error::Error>>
{
    Ok(tokio::time::timeout(Duration::from_secs(2), socket.recv()).await??)
}

同步适配器的超时返回 blocking::Error::Timeout；嵌套 Tokio 调用返回 AsyncContext；运行时创建失败返回 Runtime(io::Error)；传输失败为 Raknet(RaknetError)。SendOptions builder 使用 SendOptionsError，参数构造检查与应用到已连接 socket 的检查是两个阶段。

取消不是回滚

• send 成功表示进入传输路径，不表示远端业务已经处理。
• 取消／超时可能留下已经排队的可靠消息继续交付；批量调用可能已发出前缀。重试业务操作应使用请求 ID 和幂等处理。
• recv 共享串行消费者，并发读者要约定消息归属；批量接收开始时清空输出容器。
• flush 超时只取消等待，不停止交付；并发生产者可能不断延长 flush，因此退出前应先停止生产者。
• close 发起清理，不代替交付确认。优雅退出流程：停止生产者 → 限时 flush → close。丢弃句柄不是交付保证。

发现与诊断

RaknetSocket::ping 返回以毫秒为单位的发现 RTT 和 MOTD，不是 benchmark 中以 µs 表示的应用回显 RTT。异步调用可加应用超时，同步用 runtime.ping_timeout。发现成功不代表会话或业务登录成功。

enable_raknet_log(6) 开启进程级 error + info；1 debug、2 error、4 info 可按位组合。debug 输出会影响性能。记录版本、mtu()、raknet_version()、两端地址以及外部 socket/网络计数；公开 API 暂无完整的每连接统计或拥塞遥测对象。

生命周期 · 配置 · 排障