s0_wire 0.1.2

sync0 紧凑二进制线协议、TACK 双层确认帧与 Ed25519 自签名节点名片编解码库
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

use s0_cdc::{Rd, WireError, Wr};
use s0_const::{
  ACK_PKT_LEN, DATA_CRC_INPUT_LEN, DATA_CRC_MUL, DATA_CRC_SEED, DATA_HDR_LEN, DEFAULT_PKT,
  NACK_MAX_PARTIALS, NACK_MAX_SPANS, PKT_ACK, PKT_NACK, PKT_PUNCH, PUNCH_PKT_LEN, SID24_MASK,
  SID24_SHIFT,
};

/// 20 字节紧凑原生 UDP 数据包头
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DataHeader {
  pub session_id: u32,
  pub block_idx: u32,
  pub seg_idx: u16,
  pub seg_cnt: u16,
  pub offset_in_block: u32,
  pub payload_len: u16,
}

impl DataHeader {
  #[inline]
  fn calc_crc16(hdr18: &[u8; DATA_CRC_INPUT_LEN]) -> u16 {
    let mut acc: u32 = DATA_CRC_SEED;
    for chunk in hdr18.as_chunks::<2>().0 {
      let w = u16::from_le_bytes([chunk[0], chunk[1]]) as u32;
      acc = acc.rotate_left(5) ^ w.wrapping_mul(DATA_CRC_MUL);
    }
    (acc ^ (acc >> 16)) as u16
  }

  #[inline]
  pub fn encode(&self, out: &mut [u8; DATA_HDR_LEN]) {
    // 首字节固定为 0x00，高 3 字节存放 24-bit session_id，与控制包 (0x81/0x82/0x83) 零歧义区分
    let word0 = (self.session_id & SID24_MASK) << SID24_SHIFT;
    out[0..4].copy_from_slice(&word0.to_le_bytes());
    out[4..8].copy_from_slice(&self.block_idx.to_le_bytes());
    out[8..10].copy_from_slice(&self.seg_idx.to_le_bytes());
    out[10..12].copy_from_slice(&self.seg_cnt.to_le_bytes());
    out[12..16].copy_from_slice(&self.offset_in_block.to_le_bytes());
    out[16..18].copy_from_slice(&self.payload_len.to_le_bytes());
    let hdr18: &[u8; DATA_CRC_INPUT_LEN] = out[0..DATA_CRC_INPUT_LEN].try_into().unwrap();
    let crc = Self::calc_crc16(hdr18);
    out[DATA_CRC_INPUT_LEN..DATA_HDR_LEN].copy_from_slice(&crc.to_le_bytes());
  }

  #[inline]
  pub fn decode(buf: &[u8]) -> Result<Self, WireError> {
    if buf.len() < DATA_HDR_LEN {
      return Err(WireError::Truncated);
    }
    if buf[0] != 0 {
      return Err(WireError::BadMagic);
    }
    let hdr18: &[u8; DATA_CRC_INPUT_LEN] = buf[0..DATA_CRC_INPUT_LEN].try_into().unwrap();
    let expected = Self::calc_crc16(hdr18);
    let actual = u16::from_le_bytes([buf[18], buf[19]]);
    if expected != actual {
      return Err(WireError::CrcMismatch);
    }
    let word0 = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]);
    Ok(Self {
      session_id: word0 >> SID24_SHIFT,
      block_idx: u32::from_le_bytes([buf[4], buf[5], buf[6], buf[7]]),
      seg_idx: u16::from_le_bytes([buf[8], buf[9]]),
      seg_cnt: u16::from_le_bytes([buf[10], buf[11]]),
      offset_in_block: u32::from_le_bytes([buf[12], buf[13], buf[14], buf[15]]),
      payload_len: u16::from_le_bytes([buf[16], buf[17]]),
    })
  }
}

/// 原生 UDP 缺失块区间 NACK 包（游程编码：`[(blk_lo, blk_hi)]` + 部分到达块的分片位图 `[(blk_idx, seg_mask)]`）
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct NackPkt {
  pub session_id: u32,
  pub spans: Vec<(u32, u32)>,
  pub partials: Vec<(u32, u64)>,
}

impl NackPkt {
  #[inline]
  pub fn encode(&self, out: &mut Vec<u8>) -> Result<(), WireError> {
    Self::encode_parts(self.session_id, &self.spans, &self.partials, out)
  }

  /// 零克隆切片编码 NACK 帧（供接收端热路径直接按切片块编码，免除 `Vec` 临时分配，采用差分 + `uvar` 压缩）
  pub fn encode_parts(
    session_id: u32,
    spans: &[(u32, u32)],
    partials: &[(u32, u64)],
    out: &mut Vec<u8>,
  ) -> Result<(), WireError> {
    let mut w = Wr::new(out);
    w.u32(u32::from(PKT_NACK) | ((session_id & SID24_MASK) << SID24_SHIFT));
    let cnt = spans.len().min(NACK_MAX_SPANS);
    w.uvar(cnt as u64);
    let mut prev_hi = 0u32;
    for &(lo, hi) in &spans[..cnt] {
      let gap = lo.saturating_sub(prev_hi);
      let len = hi.saturating_sub(lo);
      w.uvar(u64::from(gap));
      w.uvar(u64::from(len));
      prev_hi = hi;
    }
    let pcnt = partials.len().min(NACK_MAX_PARTIALS);
    w.uvar(pcnt as u64);
    let mut prev_blk = 0u32;
    for &(blk, mask) in &partials[..pcnt] {
      w.uvar(u64::from(blk.saturating_sub(prev_blk)));
      w.uvar(mask);
      prev_blk = blk;
    }
    Ok(())
  }

  pub fn decode(buf: &[u8]) -> Result<Self, WireError> {
    let mut r = Rd::new(buf);
    let word0 = r.u32()?;
    if (word0 as u8) != PKT_NACK {
      return Err(WireError::BadMagic);
    }
    let session_id = word0 >> SID24_SHIFT;
    let cnt = r.uvar_usize()?.min(NACK_MAX_SPANS);
    let mut spans = Vec::with_capacity(cnt);
    let mut prev_hi = 0u32;
    for _ in 0..cnt {
      let gap = r.uvar_u32()?;
      let len = r.uvar_u32()?;
      let lo = prev_hi.saturating_add(gap);
      let hi = lo.saturating_add(len);
      if lo < hi {
        spans.push((lo, hi));
      }
      prev_hi = hi;
    }
    let mut partials = Vec::new();
    if !r.is_empty()
      && let Ok(pcnt) = r.uvar_usize()
    {
      let pcnt = pcnt.min(NACK_MAX_PARTIALS);
      partials.reserve(pcnt);
      let mut prev_blk = 0u32;
      for _ in 0..pcnt {
        if let (Ok(d_blk), Ok(mask)) = (r.uvar_u32(), r.uvar()) {
          let blk = prev_blk.saturating_add(d_blk);
          partials.push((blk, mask));
          prev_blk = blk;
        } else {
          break;
        }
      }
    }
    Ok(Self {
      session_id,
      spans,
      partials,
    })
  }
}

/// 原生 UDP 传输完成 12 字节对齐 ACK 包
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AckPkt {
  pub session_id: u32,
  pub blk_lo: u32,
  pub blk_hi: u32,
}

impl AckPkt {
  #[inline]
  pub fn encode(&self, out: &mut [u8; ACK_PKT_LEN]) {
    let word0 = u32::from(PKT_ACK) | ((self.session_id & SID24_MASK) << SID24_SHIFT);
    out[0..4].copy_from_slice(&word0.to_le_bytes());
    out[4..8].copy_from_slice(&self.blk_lo.to_le_bytes());
    out[8..ACK_PKT_LEN].copy_from_slice(&self.blk_hi.to_le_bytes());
  }

  #[inline]
  pub fn decode(buf: &[u8]) -> Result<Self, WireError> {
    if buf.len() < ACK_PKT_LEN {
      return Err(WireError::Truncated);
    }
    if buf[0] != PKT_ACK {
      return Err(WireError::BadMagic);
    }
    let word0 = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]);
    Ok(Self {
      session_id: word0 >> SID24_SHIFT,
      blk_lo: u32::from_le_bytes([buf[4], buf[5], buf[6], buf[7]]),
      blk_hi: u32::from_le_bytes([buf[8], buf[9], buf[10], buf[11]]),
    })
  }
}

/// 构造 4 字节对齐 UDP 打洞探测包（`PKT_PUNCH | (session_id << 8)`）
#[inline]
pub const fn encode_punch(session_id: u32) -> [u8; PUNCH_PKT_LEN] {
  ((PKT_PUNCH as u32) | ((session_id & SID24_MASK) << SID24_SHIFT)).to_le_bytes()
}

/// 构造填充至 `DEFAULT_PKT` (1400 B) 的 Path MTU 探测打洞包（RFC 8899 DPLPMTUD）
#[inline]
pub fn encode_punch_padded(session_id: u32) -> [u8; DEFAULT_PKT] {
  let mut out = [0u8; DEFAULT_PKT];
  out[0..PUNCH_PKT_LEN].copy_from_slice(&encode_punch(session_id));
  out
}

/// 解码 UDP 打洞探测包（兼容 4B 保底包与 1400B PMTUD 填充探测包）并返回 24-bit `session_id`
#[inline]
pub fn decode_punch(buf: &[u8]) -> Result<u32, WireError> {
  if buf.len() < PUNCH_PKT_LEN {
    return Err(WireError::Truncated);
  }
  if buf[0] != PKT_PUNCH {
    return Err(WireError::BadMagic);
  }
  Ok(u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]) >> SID24_SHIFT)
}