bb392507bd
- signaling.rs: 信令消息契约 + NAT 画像/打洞前景诊断 + 证书指纹 - 明确不含 relay/TURN：打洞失败必须给出可执行原因（PunchFailReason::user_hint） - 时间对齐不做时钟同步：服务器按两侧 RTT 下发不同 start_in_ms - 保活按 binding_timeout_s 折半（keepalive_secs）
758 lines
28 KiB
Rust
758 lines
28 KiB
Rust
//! P2P 打洞信令协议（`common/` 契约，agent / viewer / 信令服务三端共享）。
|
||
//!
|
||
//! ## 职责边界（重要，改动前必读）
|
||
//! - **信令服务器只做两件事**：① 把双方的外部视角（公网映射地址 + NAT 行为）拼起来回推给对端；
|
||
//! ② 下发同步打洞计划，让双方在同一绝对时刻开始发包。建连完成后信令与本次会话再无关系，
|
||
//! 不承载任何媒体流量。
|
||
//! - **本协议不含中继**（无 relay / TURN 消息）。打洞失败就是失败，因此必须把原因讲清楚
|
||
//! （见 [`PunchFailReason::user_hint`]），不允许让用户停在"连接中"。
|
||
//! - 会话建立后走 QUIC：**不要**再用 viewer 现有的 `SkipVerify`，改用
|
||
//! [`EndpointInfo::cert_fingerprint`] 做公钥钉扎。
|
||
//!
|
||
//! ## 线格式
|
||
//! 类型只依赖 `serde`，不绑定具体编码。建议信令走 WSS/443（最容易穿过企业防火墙），
|
||
//! 编码用 JSON 便于抓包排查；本模块单元测试用 bincode 做往返校验，两者不冲突。
|
||
//!
|
||
//! ## 一次会话的时序
|
||
//! ```text
|
||
//! agent 信令服务器 viewer
|
||
//! |-- Register(info) ------->|<------- Register(info) -----|
|
||
//! |<-- Registered(observed) -|------ Registered(observed) ->|
|
||
//! |<-- PeerReady(peer info) -|------ PeerReady(peer info) -->|
|
||
//! |<-- PunchPlan(start_in) --|------ PunchPlan(start_in) --->|
|
||
//! | （双方同时向对端候选列表发包，多轮） |
|
||
//! |<========= 打通：UDP 直连 → QUIC 握手 + 证书钉扎 =========>|
|
||
//! |--- PunchReport(Connected) ->|<---- PunchReport ----------|
|
||
//! ```
|
||
|
||
use serde::{Deserialize, Serialize};
|
||
use std::net::{IpAddr, SocketAddr};
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 常量
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/// 信令协议版本。双方不一致时服务器应拒绝并提示升级，不要尝试兼容旧版。
|
||
pub const SIGNALING_VERSION: u16 = 1;
|
||
|
||
/// 打洞用的 UDP 端口，与 agent 当前监听端口一致。
|
||
/// 固定端口对两件事有直接好处：NAT 端口预测、以及用户手动做端口转发。
|
||
pub const PUNCH_UDP_PORT: u16 = 47800;
|
||
|
||
/// 信令默认端口。走 WSS/443 是因为企业防火墙通常只放行 80/443。
|
||
pub const SIGNALING_DEFAULT_PORT: u16 = 443;
|
||
|
||
/// 单次打洞的默认轮数。
|
||
pub const PUNCH_DEFAULT_ROUNDS: u8 = 3;
|
||
|
||
/// 打洞轮间隔（毫秒）。太短来不及让 NAT 建立映射，太长用户等不及。
|
||
pub const PUNCH_ROUND_INTERVAL_MS: u16 = 200;
|
||
|
||
/// 候选地址数量上限（含预测端口）。超出即截断，防止滥用与报文膨胀。
|
||
pub const MAX_CANDIDATES: usize = 32;
|
||
|
||
/// NAT 绑定保活周期的下限/上限（秒）。
|
||
pub const KEEPALIVE_MIN_S: u16 = 5;
|
||
pub const KEEPALIVE_MAX_S: u16 = 60;
|
||
|
||
/// 未测出 NAT 绑定超时时的保活默认值（秒）。家用 NAT 的 UDP 映射普遍 30s 左右超时。
|
||
pub const KEEPALIVE_DEFAULT_S: u16 = 15;
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 基础类型
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/// 端点角色。打洞成功后 agent 作为 QUIC server，viewer 主动 connect。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum Role {
|
||
/// 被控端
|
||
Agent,
|
||
/// 主控端
|
||
Viewer,
|
||
}
|
||
|
||
impl Role {
|
||
pub fn peer(self) -> Role {
|
||
match self {
|
||
Role::Agent => Role::Viewer,
|
||
Role::Viewer => Role::Agent,
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 候选地址的来源，决定打洞优先级。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum CandidateKind {
|
||
/// 本机网卡地址（同局域网直连用，最省事）
|
||
Host,
|
||
/// 经 UPnP / NAT-PMP / PCP 主动申请的端口映射（把对称 NAT 变成可直连）
|
||
Upnp,
|
||
/// 信令服务器观察到的公网映射（等价于一次 STUN binding，server-reflexive）
|
||
Reflexive,
|
||
/// 按 NAT 端口分配规律预测出的端口
|
||
Predicted,
|
||
}
|
||
|
||
/// 一个候选地址。IPv6 有公网地址时基本等同直连，因此固定排在 IPv4 之前。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct Candidate {
|
||
pub addr: SocketAddr,
|
||
pub kind: CandidateKind,
|
||
}
|
||
|
||
impl Candidate {
|
||
pub fn new(addr: SocketAddr, kind: CandidateKind) -> Self {
|
||
Self { addr, kind }
|
||
}
|
||
|
||
pub fn is_ipv6(&self) -> bool {
|
||
self.addr.is_ipv6()
|
||
}
|
||
|
||
/// 打分越高越先打。IPv6（+100）> UPnP 显式映射 > 本机地址 > 公网反射 > 端口预测。
|
||
pub fn score(&self) -> u16 {
|
||
let base = match self.kind {
|
||
CandidateKind::Upnp => 90,
|
||
CandidateKind::Host => 80,
|
||
CandidateKind::Reflexive => 60,
|
||
CandidateKind::Predicted => 40,
|
||
};
|
||
if self.is_ipv6() {
|
||
base + 100
|
||
} else {
|
||
base
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 按优先级从高到低排序（`sort_by` 是稳定排序，同分保持调用方给出的顺序）。
|
||
pub fn sort_candidates(v: &mut [Candidate]) {
|
||
v.sort_by(|a, b| b.score().cmp(&a.score()));
|
||
}
|
||
|
||
/// 清洗对端送来的候选列表：丢弃端口 0、按地址去重、截断到 [`MAX_CANDIDATES`]。
|
||
///
|
||
/// 对端数据一律视为不可信输入；打洞阶段每个候选都会产生实际发包，必须设上限。
|
||
pub fn sanitize_candidates(v: Vec<Candidate>) -> Vec<Candidate> {
|
||
let mut out: Vec<Candidate> = Vec::with_capacity(v.len().min(MAX_CANDIDATES));
|
||
for c in v {
|
||
if c.addr.port() == 0 {
|
||
continue;
|
||
}
|
||
if out.iter().any(|e| e.addr == c.addr) {
|
||
continue;
|
||
}
|
||
if out.len() == MAX_CANDIDATES {
|
||
break;
|
||
}
|
||
out.push(c);
|
||
}
|
||
out
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// NAT 画像与诊断
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/// RFC 4787 §4.1 映射行为：同一个内网 socket 的公网端口是否随目标变化。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum MappingBehavior {
|
||
/// 端点无关（full cone / restricted cone）：打洞最理想
|
||
EndpointIndependent,
|
||
/// 地址相关
|
||
AddressDependent,
|
||
/// 地址+端口相关（即"对称 NAT"）
|
||
AddressAndPortDependent,
|
||
Unknown,
|
||
}
|
||
|
||
/// RFC 4787 §5.1 过滤行为：外部包能否进得来。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum FilteringBehavior {
|
||
EndpointIndependent,
|
||
AddressDependent,
|
||
AddressAndPortDependent,
|
||
Unknown,
|
||
}
|
||
|
||
/// 公网端口分配规律，决定端口预测是否可用。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum PortAllocation {
|
||
/// 保持内网端口
|
||
Preserved,
|
||
/// 递增分配（可预测，端口预测值得一试）
|
||
Sequential,
|
||
/// 随机（端口预测无效）
|
||
Random,
|
||
Unknown,
|
||
}
|
||
|
||
/// NAT 行为画像。信令握手阶段顺带测出，用于：① 决定打洞策略；② 失败时给用户解释。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct NatProfile {
|
||
pub mapping: MappingBehavior,
|
||
pub filtering: FilteringBehavior,
|
||
pub allocation: PortAllocation,
|
||
/// NAT 绑定超时（秒）。未测出为 `None`，此时用 [`KEEPALIVE_DEFAULT_S`]。
|
||
pub binding_timeout_s: Option<u16>,
|
||
/// 是否支持 hairpinning（同一 NAT 内的两端可互连）
|
||
pub hairpinning: bool,
|
||
}
|
||
|
||
impl Default for NatProfile {
|
||
fn default() -> Self {
|
||
Self {
|
||
mapping: MappingBehavior::Unknown,
|
||
filtering: FilteringBehavior::Unknown,
|
||
allocation: PortAllocation::Unknown,
|
||
binding_timeout_s: None,
|
||
hairpinning: false,
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 打洞前景评估，直接用于 UI 提示与"是否值得继续重试"的决策。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum PunchOutlook {
|
||
/// 锥形 NAT 或公网 IPv6，基本必成
|
||
Likely,
|
||
/// 需要多轮重试 / 端口预测，可能成
|
||
Possible,
|
||
/// 对称 NAT 且端口不可预测，通常打不通
|
||
Unlikely,
|
||
/// 运营商级 NAT（CGNAT），无中继方案下无解 —— 不必浪费多轮打洞
|
||
Hopeless,
|
||
}
|
||
|
||
/// 运营商级 NAT 判定：RFC 6598 共享地址空间 `100.64.0.0/10`。
|
||
///
|
||
/// 命中即无中继不可达，应立刻给出"换网络"提示，而不是让用户等完所有打洞轮次。
|
||
pub fn is_cgnat(observed: IpAddr) -> bool {
|
||
match observed {
|
||
IpAddr::V4(v4) => {
|
||
let o = v4.octets();
|
||
o[0] == 100 && (64..=127).contains(&o[1])
|
||
}
|
||
IpAddr::V6(_) => false,
|
||
}
|
||
}
|
||
|
||
/// 综合 NAT 画像与观察到的公网地址，评估打洞前景。
|
||
///
|
||
/// `observed_public` 是信令服务器看到的本端公网映射（IPv6 时即本机全局地址）。
|
||
pub fn punch_outlook(nat: &NatProfile, observed_public: IpAddr) -> PunchOutlook {
|
||
// IPv6 没有 NAT 可言，只要双方都有公网 v6 就是真直连。
|
||
if observed_public.is_ipv6() {
|
||
return PunchOutlook::Likely;
|
||
}
|
||
if is_cgnat(observed_public) {
|
||
return PunchOutlook::Hopeless;
|
||
}
|
||
match nat.mapping {
|
||
MappingBehavior::EndpointIndependent => PunchOutlook::Likely,
|
||
MappingBehavior::AddressDependent => PunchOutlook::Possible,
|
||
MappingBehavior::AddressAndPortDependent => match nat.allocation {
|
||
// 对称 NAT 但端口可预测 → 端口预测 + 多轮重试仍有机会
|
||
PortAllocation::Sequential | PortAllocation::Preserved => PunchOutlook::Possible,
|
||
PortAllocation::Random | PortAllocation::Unknown => PunchOutlook::Unlikely,
|
||
},
|
||
// 测不出来就按"可能"处理，先试再说
|
||
MappingBehavior::Unknown => PunchOutlook::Possible,
|
||
}
|
||
}
|
||
|
||
/// 双方协商保活周期（秒）：取双方绑定超时的较小值再折半，并夹在
|
||
/// [`KEEPALIVE_MIN_S`]..=[`KEEPALIVE_MAX_S`] 之间。
|
||
///
|
||
/// 洞是靠出站包维持的，超时后会静默关闭 —— 表现为"连上了一会儿就断"。
|
||
pub fn keepalive_secs(mine: &NatProfile, theirs: &NatProfile) -> u16 {
|
||
let t = match (mine.binding_timeout_s, theirs.binding_timeout_s) {
|
||
(Some(a), Some(b)) => a.min(b),
|
||
(Some(a), None) => a,
|
||
(None, Some(b)) => b,
|
||
(None, None) => KEEPALIVE_DEFAULT_S,
|
||
};
|
||
(t / 2).clamp(KEEPALIVE_MIN_S, KEEPALIVE_MAX_S)
|
||
}
|
||
|
||
/// 服务器侧计算某个客户端的打洞启动延迟（相对 PunchPlan 送达时刻）。
|
||
///
|
||
/// 两侧 RTT 不同：若下发同一个延迟，RTT 大的一方会晚发包，洞就打不上。
|
||
/// 以双方最大 RTT 为基准、减去自身 RTT 的一半，即可在**不做时钟同步**的前提下
|
||
/// 让两侧的绝对开打时刻对齐（误差约等于单程抖动）。
|
||
///
|
||
/// ```text
|
||
/// start_in_ms = max_rtt_ms / 2 + margin_ms - own_rtt_ms / 2
|
||
/// ```
|
||
pub fn punch_start_delay_ms(own_rtt_ms: u16, max_rtt_ms: u16, margin_ms: u16) -> u16 {
|
||
let base = max_rtt_ms as u32 / 2 + margin_ms as u32;
|
||
let own_half = own_rtt_ms as u32 / 2;
|
||
base.saturating_sub(own_half).min(u16::MAX as u32) as u16
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 证书指纹（替代 viewer 现有的 SkipVerify）
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/// 自签证书公钥指纹（SHA-256 的 32 字节裸值）。
|
||
///
|
||
/// agent 生成自签证书后把指纹经信令发布，viewer 用它对 QUIC 连接做**公钥钉扎**，
|
||
/// 从而去掉 `viewer/src/main.rs` 里的 `SkipVerify`（公网环境不可接受）。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct CertFingerprint(pub [u8; 32]);
|
||
|
||
impl CertFingerprint {
|
||
/// 小写十六进制（64 字符）
|
||
pub fn to_hex(&self) -> String {
|
||
self.0.iter().map(|b| format!("{b:02x}")).collect()
|
||
}
|
||
|
||
/// 解析 64 字符十六进制；长度不符或含非十六进制字符返回 `None`。
|
||
pub fn from_hex(s: &str) -> Option<Self> {
|
||
let s = s.trim();
|
||
if s.len() != 64 {
|
||
return None;
|
||
}
|
||
let mut out = [0u8; 32];
|
||
for (i, chunk) in s.as_bytes().chunks(2).enumerate() {
|
||
let hi = (chunk[0] as char).to_digit(16)?;
|
||
let lo = (chunk[1] as char).to_digit(16)?;
|
||
out[i] = (hi * 16 + lo) as u8;
|
||
}
|
||
Some(Self(out))
|
||
}
|
||
}
|
||
|
||
impl std::fmt::Display for CertFingerprint {
|
||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||
f.write_str(&self.to_hex())
|
||
}
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 端点信息与消息
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/// 连通性相关的能力标志。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
|
||
pub struct Capabilities {
|
||
/// 已成功获得 UPnP / NAT-PMP / PCP 端口映射
|
||
pub upnp_mapped: bool,
|
||
/// 本机具备可用 IPv6 出口
|
||
pub ipv6_available: bool,
|
||
}
|
||
|
||
/// 一个端点的完整连通性描述，随 Register / PeerReady 交换。
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub struct EndpointInfo {
|
||
pub role: Role,
|
||
/// 本端打洞用的 UDP 监听端口（通常等于 [`PUNCH_UDP_PORT`]）
|
||
pub port: u16,
|
||
/// 候选地址，发送前请用 [`sort_candidates`] 排好序
|
||
pub candidates: Vec<Candidate>,
|
||
pub nat: NatProfile,
|
||
/// QUIC 证书公钥指纹，供对端钉扎
|
||
pub cert_fingerprint: CertFingerprint,
|
||
pub caps: Capabilities,
|
||
}
|
||
|
||
/// 打洞失败原因。**无中继方案的用户体验下限就在这里** —— 每种原因都要能翻译成
|
||
/// 用户能照做的一句话，见 [`PunchFailReason::user_hint`]。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum PunchFailReason {
|
||
/// 所有候选都无回包（最常见：双方都是地址+端口相关型 NAT）
|
||
NoCandidateReachable,
|
||
/// 双方均为对称 NAT 且端口不可预测
|
||
SymmetricNat,
|
||
/// 运营商级 NAT（100.64/10）
|
||
Cgnat,
|
||
/// 本机 UDP 出站被策略封锁（企业防火墙常见）
|
||
UdpBlocked,
|
||
/// 对端提前退出
|
||
PeerAborted,
|
||
/// 超时未收到任何回包
|
||
Timeout,
|
||
}
|
||
|
||
impl PunchFailReason {
|
||
/// 面向用户的中文处置建议。不要吞掉这个信息 —— 用户看不到原因就只会认为"这软件连不上"。
|
||
pub fn user_hint(self) -> &'static str {
|
||
match self {
|
||
PunchFailReason::NoCandidateReachable => {
|
||
"双方网络都无法直接互通。请在被控端路由器开启 UPnP 后重试，或双方改用 IPv6 网络。"
|
||
}
|
||
PunchFailReason::SymmetricNat => {
|
||
"当前网络是对称型 NAT，无法直连。请在被控端路由器开启 UPnP，或更换网络后重试。"
|
||
}
|
||
PunchFailReason::Cgnat => {
|
||
"当前处于运营商级 NAT（大内网），无法直连。请改用 IPv6 网络，或换一条能拿到公网地址的线路。"
|
||
}
|
||
PunchFailReason::UdpBlocked => {
|
||
"当前网络的防火墙拦截了 UDP 出站。请更换网络（如切换手机热点）后重试。"
|
||
}
|
||
PunchFailReason::PeerAborted => "对端已取消本次连接。",
|
||
PunchFailReason::Timeout => "连接超时，可能是网络波动。请重试一次。",
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 打洞结果。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum PunchOutcome {
|
||
/// 打通：`peer` 为真正生效的对端地址，`rtt_ms` 为实测往返
|
||
Connected { peer: SocketAddr, rtt_ms: u16 },
|
||
Failed { reason: PunchFailReason },
|
||
}
|
||
|
||
impl PunchOutcome {
|
||
pub fn is_connected(&self) -> bool {
|
||
matches!(self, PunchOutcome::Connected { .. })
|
||
}
|
||
|
||
/// 已连通返回 `None`，失败返回给用户看的建议。
|
||
pub fn user_hint(&self) -> Option<&'static str> {
|
||
match self {
|
||
PunchOutcome::Connected { .. } => None,
|
||
PunchOutcome::Failed { reason } => Some(reason.user_hint()),
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 信令层错误码。
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum SignalError {
|
||
/// [`SIGNALING_VERSION`] 不匹配（客户端需升级）
|
||
VersionMismatch,
|
||
/// 验证码错误或已过期
|
||
BadAuth,
|
||
SessionNotFound,
|
||
PeerOffline,
|
||
/// 候选地址数量超限
|
||
TooManyCandidates,
|
||
RateLimited,
|
||
Internal,
|
||
}
|
||
|
||
/// 客户端 → 信令服务器。
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum ClientMsg {
|
||
/// 注册并等待对端。`auth` 必须是一次性验证码（不是 MVP 里的固定 123456）。
|
||
Register {
|
||
version: u16,
|
||
/// 会话/设备标识；服务器据此配对两端
|
||
session: String,
|
||
auth: String,
|
||
info: EndpointInfo,
|
||
},
|
||
/// 候选变化补报：UPnP 映射稍后才成功、或网卡地址变化时用。
|
||
UpdateCandidates {
|
||
session: String,
|
||
candidates: Vec<Candidate>,
|
||
nat: NatProfile,
|
||
},
|
||
/// 打洞结果回报。服务器可据此记录有效路径、统计成功率。
|
||
PunchReport {
|
||
session: String,
|
||
plan_id: u32,
|
||
outcome: PunchOutcome,
|
||
},
|
||
/// 保活：维持信令长连接，同时刷新本端 NAT 绑定。
|
||
Keepalive { session: String },
|
||
Bye {
|
||
session: String,
|
||
reason: String,
|
||
},
|
||
}
|
||
|
||
/// 信令服务器 → 客户端。
|
||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||
pub enum ServerMsg {
|
||
/// 注册成功。`observed` 是服务器看到的本端公网映射，等价于一次 STUN binding；
|
||
/// `rtt_ms` 供打洞计划做时间对齐（见 [`punch_start_delay_ms`]）。
|
||
Registered {
|
||
session: String,
|
||
observed: SocketAddr,
|
||
/// 对端是否已在场。`false` 时应等待 [`ServerMsg::PeerReady`]。
|
||
peer_present: bool,
|
||
rtt_ms: u16,
|
||
},
|
||
/// 对端已就绪，附带其候选地址、NAT 画像与证书指纹。
|
||
PeerReady {
|
||
peer: EndpointInfo,
|
||
peer_observed: SocketAddr,
|
||
/// 打洞前景，可直接显示给用户（"很可能直连成功" / "当前网络可能无法直连"）
|
||
outlook: PunchOutlook,
|
||
},
|
||
/// 同步打洞计划。
|
||
///
|
||
/// `start_in_ms` 是**相对本消息**的延迟，服务器对两侧下发不同的值以使双方在同一
|
||
/// 绝对时刻开打 —— 因此本协议不要求两端时钟同步。
|
||
PunchPlan {
|
||
plan_id: u32,
|
||
start_in_ms: u16,
|
||
rounds: u8,
|
||
round_interval_ms: u16,
|
||
/// 对端候选（已排序、已清洗）；本端需对其中每个地址发包
|
||
peer_candidates: Vec<Candidate>,
|
||
},
|
||
/// 打洞结果确认（用于 UI 显示"直连成功，RTT xx ms"）。
|
||
PunchAck { plan_id: u32, outcome: PunchOutcome },
|
||
Error { code: SignalError, message: String },
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 测试
|
||
// ---------------------------------------------------------------------------
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
fn fp(byte: u8) -> CertFingerprint {
|
||
CertFingerprint([byte; 32])
|
||
}
|
||
|
||
fn info(role: Role) -> EndpointInfo {
|
||
let mut candidates = vec![
|
||
Candidate::new("1.2.3.4:47800".parse().unwrap(), CandidateKind::Reflexive),
|
||
Candidate::new("[2001:db8::1]:47800".parse().unwrap(), CandidateKind::Host),
|
||
Candidate::new("192.168.1.5:47800".parse().unwrap(), CandidateKind::Upnp),
|
||
];
|
||
sort_candidates(&mut candidates);
|
||
EndpointInfo {
|
||
role,
|
||
port: PUNCH_UDP_PORT,
|
||
candidates,
|
||
nat: NatProfile {
|
||
mapping: MappingBehavior::AddressDependent,
|
||
filtering: FilteringBehavior::AddressAndPortDependent,
|
||
allocation: PortAllocation::Sequential,
|
||
binding_timeout_s: Some(30),
|
||
hairpinning: false,
|
||
},
|
||
cert_fingerprint: fp(0xab),
|
||
caps: Capabilities {
|
||
upnp_mapped: true,
|
||
ipv6_available: true,
|
||
},
|
||
}
|
||
}
|
||
|
||
fn client_msgs() -> Vec<ClientMsg> {
|
||
vec![
|
||
ClientMsg::Register {
|
||
version: SIGNALING_VERSION,
|
||
session: "dev-1".into(),
|
||
auth: "0f3a91".into(),
|
||
info: info(Role::Agent),
|
||
},
|
||
ClientMsg::UpdateCandidates {
|
||
session: "dev-1".into(),
|
||
candidates: vec![Candidate::new(
|
||
"5.6.7.8:47800".parse().unwrap(),
|
||
CandidateKind::Predicted,
|
||
)],
|
||
nat: NatProfile::default(),
|
||
},
|
||
ClientMsg::PunchReport {
|
||
session: "dev-1".into(),
|
||
plan_id: 7,
|
||
outcome: PunchOutcome::Connected {
|
||
peer: "9.9.9.9:47800".parse().unwrap(),
|
||
rtt_ms: 42,
|
||
},
|
||
},
|
||
ClientMsg::PunchReport {
|
||
session: "dev-1".into(),
|
||
plan_id: 8,
|
||
outcome: PunchOutcome::Failed {
|
||
reason: PunchFailReason::Cgnat,
|
||
},
|
||
},
|
||
ClientMsg::Keepalive {
|
||
session: "dev-1".into(),
|
||
},
|
||
ClientMsg::Bye {
|
||
session: "dev-1".into(),
|
||
reason: "user quit".into(),
|
||
},
|
||
]
|
||
}
|
||
|
||
fn server_msgs() -> Vec<ServerMsg> {
|
||
vec![
|
||
ServerMsg::Registered {
|
||
session: "dev-1".into(),
|
||
observed: "203.0.113.9:51234".parse().unwrap(),
|
||
peer_present: true,
|
||
rtt_ms: 38,
|
||
},
|
||
ServerMsg::PeerReady {
|
||
peer: info(Role::Viewer),
|
||
peer_observed: "203.0.113.10:51235".parse().unwrap(),
|
||
outlook: PunchOutlook::Likely,
|
||
},
|
||
ServerMsg::PunchPlan {
|
||
plan_id: 9,
|
||
start_in_ms: 130,
|
||
rounds: PUNCH_DEFAULT_ROUNDS,
|
||
round_interval_ms: PUNCH_ROUND_INTERVAL_MS,
|
||
peer_candidates: info(Role::Viewer).candidates,
|
||
},
|
||
ServerMsg::PunchAck {
|
||
plan_id: 9,
|
||
outcome: PunchOutcome::Failed {
|
||
reason: PunchFailReason::SymmetricNat,
|
||
},
|
||
},
|
||
ServerMsg::Error {
|
||
code: SignalError::VersionMismatch,
|
||
message: "server expects v1".into(),
|
||
},
|
||
]
|
||
}
|
||
|
||
#[test]
|
||
fn bincode_roundtrip_client_msgs() {
|
||
for m in client_msgs() {
|
||
let bytes = bincode::serialize(&m).expect("serialize");
|
||
let back: ClientMsg = bincode::deserialize(&bytes).expect("deserialize");
|
||
assert_eq!(m, back);
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn bincode_roundtrip_server_msgs() {
|
||
for m in server_msgs() {
|
||
let bytes = bincode::serialize(&m).expect("serialize");
|
||
let back: ServerMsg = bincode::deserialize(&bytes).expect("deserialize");
|
||
assert_eq!(m, back);
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn candidates_sorted_ipv6_first_then_upnp() {
|
||
let mut v = vec![
|
||
Candidate::new("1.2.3.4:47800".parse().unwrap(), CandidateKind::Reflexive),
|
||
Candidate::new("[2001:db8::1]:47800".parse().unwrap(), CandidateKind::Host),
|
||
Candidate::new("192.168.1.5:47800".parse().unwrap(), CandidateKind::Upnp),
|
||
];
|
||
sort_candidates(&mut v);
|
||
assert!(v[0].is_ipv6(), "IPv6 候选必须排第一");
|
||
assert_eq!(v[1].kind, CandidateKind::Upnp);
|
||
assert_eq!(v[2].kind, CandidateKind::Reflexive);
|
||
}
|
||
|
||
#[test]
|
||
fn sanitize_dedups_and_bounds() {
|
||
let dup = Candidate::new("1.2.3.4:47800".parse().unwrap(), CandidateKind::Host);
|
||
let zero_port = Candidate::new("1.2.3.4:0".parse().unwrap(), CandidateKind::Host);
|
||
let mut v = vec![dup, dup, zero_port];
|
||
v.extend((0..MAX_CANDIDATES + 5).map(|i| {
|
||
Candidate::new(
|
||
format!("10.0.{}.{}:47800", i / 250, i % 250).parse().unwrap(),
|
||
CandidateKind::Predicted,
|
||
)
|
||
}));
|
||
let out = sanitize_candidates(v);
|
||
assert_eq!(out.len(), MAX_CANDIDATES);
|
||
assert!(out.iter().all(|c| c.addr.port() != 0));
|
||
let mut addrs: Vec<_> = out.iter().map(|c| c.addr).collect();
|
||
addrs.sort();
|
||
addrs.dedup();
|
||
assert_eq!(addrs.len(), out.len());
|
||
}
|
||
|
||
#[test]
|
||
fn outlook_covers_ipv6_cgnat_and_symmetric() {
|
||
let v6: IpAddr = "2001:db8::1".parse().unwrap();
|
||
let public: IpAddr = "203.0.113.9".parse().unwrap();
|
||
let cgnat: IpAddr = "100.64.1.1".parse().unwrap();
|
||
|
||
let mut nat = NatProfile::default();
|
||
assert_eq!(punch_outlook(&nat, v6), PunchOutlook::Likely);
|
||
assert_eq!(punch_outlook(&nat, cgnat), PunchOutlook::Hopeless);
|
||
assert!(is_cgnat("100.127.255.254".parse().unwrap()));
|
||
assert!(!is_cgnat("100.128.0.1".parse().unwrap()));
|
||
|
||
nat.mapping = MappingBehavior::EndpointIndependent;
|
||
assert_eq!(punch_outlook(&nat, public), PunchOutlook::Likely);
|
||
|
||
nat.mapping = MappingBehavior::AddressAndPortDependent;
|
||
nat.allocation = PortAllocation::Sequential;
|
||
assert_eq!(punch_outlook(&nat, public), PunchOutlook::Possible);
|
||
|
||
nat.allocation = PortAllocation::Random;
|
||
assert_eq!(punch_outlook(&nat, public), PunchOutlook::Unlikely);
|
||
}
|
||
|
||
#[test]
|
||
fn keepalive_halves_binding_timeout_and_clamps() {
|
||
let a = NatProfile {
|
||
binding_timeout_s: Some(30),
|
||
..Default::default()
|
||
};
|
||
let b = NatProfile {
|
||
binding_timeout_s: Some(20),
|
||
..Default::default()
|
||
};
|
||
assert_eq!(keepalive_secs(&a, &b), 10);
|
||
assert_eq!(keepalive_secs(&NatProfile::default(), &NatProfile::default()), 7);
|
||
let short = NatProfile {
|
||
binding_timeout_s: Some(4),
|
||
..Default::default()
|
||
};
|
||
assert_eq!(keepalive_secs(&short, &short), KEEPALIVE_MIN_S);
|
||
let long = NatProfile {
|
||
binding_timeout_s: Some(600),
|
||
..Default::default()
|
||
};
|
||
assert_eq!(keepalive_secs(&long, &long), KEEPALIVE_MAX_S);
|
||
}
|
||
|
||
#[test]
|
||
fn punch_start_delay_aligns_absolute_time() {
|
||
// RTT 大的一方应该更早出发，使两侧绝对开打时刻一致。
|
||
let slow = punch_start_delay_ms(200, 200, 100);
|
||
let fast = punch_start_delay_ms(20, 200, 100);
|
||
assert_eq!(slow, 100);
|
||
assert_eq!(fast, 190);
|
||
assert!(fast > slow);
|
||
}
|
||
|
||
#[test]
|
||
fn cert_fingerprint_hex_roundtrip() {
|
||
let f = fp(0x0f);
|
||
let hex = f.to_hex();
|
||
assert_eq!(hex.len(), 64);
|
||
assert_eq!(CertFingerprint::from_hex(&hex), Some(f));
|
||
assert_eq!(CertFingerprint::from_hex(&hex.to_uppercase()), Some(f));
|
||
assert_eq!(CertFingerprint::from_hex("00"), None);
|
||
assert_eq!(CertFingerprint::from_hex(&"z".repeat(64)), None);
|
||
}
|
||
|
||
#[test]
|
||
fn fail_reasons_all_have_user_hints() {
|
||
let all = [
|
||
PunchFailReason::NoCandidateReachable,
|
||
PunchFailReason::SymmetricNat,
|
||
PunchFailReason::Cgnat,
|
||
PunchFailReason::UdpBlocked,
|
||
PunchFailReason::PeerAborted,
|
||
PunchFailReason::Timeout,
|
||
];
|
||
for r in all {
|
||
assert!(!r.user_hint().is_empty());
|
||
let o = PunchOutcome::Failed { reason: r };
|
||
assert!(!o.is_connected());
|
||
assert!(o.user_hint().is_some());
|
||
}
|
||
let ok = PunchOutcome::Connected {
|
||
peer: "1.2.3.4:47800".parse().unwrap(),
|
||
rtt_ms: 30,
|
||
};
|
||
assert!(ok.is_connected());
|
||
assert!(ok.user_hint().is_none());
|
||
}
|
||
}
|