zenith_foundation/
prefix_int.rs

1//! RFC 7541 §5.1 前缀整数编解码（HPACK / QPACK 共享唯一实现）
2//!
3//! HPACK（RFC 7541）与 QPACK（RFC 9204）共用同一种「前缀整数」线格式：
4//! 首字节高 `prefix_bits` 位为前缀（类型标识），低 `8 - prefix_bits` 位承载
5//! 低位整数；若前缀位全 1 则后续字节以 7-bit 组继续（每字节高位置 1 表示延续）。
6//!
7//! 本模块为全 workspace 唯一实现，禁止在 `zenith-http2` / `zenith-http3`
8//! 内重复实现（历史双实现已收敛于此）。解码器 fail-closed：输入截断、
9//! 扩展位过多、值超 `u64` 一律返回 `None`，绝不 panic。
10
11/// 编码前缀整数（RFC 7541 §5.1）
12///
13/// - `prefix_bits`：前缀位数（1-8），越界时静默返回（调用方保证合法）。
14/// - `prefix_pattern`：类型标识位，OR 到首字节高位。
15///
16/// 写入 `out`；`value` 为无符号整数（HPACK 用 `u32`、QPACK 用 `u64`，均无损提升）。
17#[inline]
18pub fn encode_prefix_integer(
19    out: &mut Vec<u8>,
20    value: u64,
21    prefix_bits: u8,
22    prefix_pattern: u8,
23) {
24    if prefix_bits == 0 || prefix_bits > 8 {
25        return;
26    }
27    let mask = (1u64 << prefix_bits) - 1;
28    if value < mask {
29        out.push(prefix_pattern | (value as u8));
30        return;
31    }
32    out.push(prefix_pattern | mask as u8);
33    let mut v = value - mask;
34    while v >= 0x80 {
35        out.push(((v as u8) & 0x7F) | 0x80);
36        v >>= 7;
37    }
38    out.push(v as u8);
39}
40
41/// 解码前缀整数（RFC 7541 §5.1）
42///
43/// 返回 `(value, consumed_bytes)`；`value` 为 `u64`（HPACK 调用方需自行收窄到 `u32`）。
44///
45/// # 安全（fail-closed）
46/// - 输入截断 / 起始为空 → `None`
47/// - 扩展位过多（`m > 56`，超出 `u64` 可承载范围）→ `None`
48/// - 乘法/加法溢出 → `None`（checked 算术，杜绝 debug panic / release 回绕）
49#[inline]
50pub fn decode_prefix_integer(data: &[u8], prefix_bits: u8) -> Option<(u64, usize)> {
51    if data.is_empty() || prefix_bits == 0 || prefix_bits > 8 {
52        return None;
53    }
54    // 用 u16 计算 mask，避免 prefix_bits = 8 时 1u8 << 8 溢出
55    let mask = ((1u16 << prefix_bits as u16) - 1) as u8;
56    let first = data[0] & mask;
57    let mut value = first as u64;
58    if first < mask {
59        return Some((value, 1));
60    }
61    let mut m: u32 = 0;
62    let mut i: usize = 1;
63    loop {
64        // 扩展位过多（u64 上限）：在读入下一个延续字节之前检查，
65        // 超限 fail-closed，杜绝死循环 / 溢出。
66        if m > 56 {
67            return None;
68        }
69        let Some(&b) = data.get(i) else {
70            return None; // 输入截断
71        };
72        i += 1;
73        let shift = 1u64.checked_shl(m)?;
74        let contribution = ((b & 0x7F) as u64).checked_mul(shift)?;
75        value = value.checked_add(contribution)?;
76        m = m.checked_add(7)?;
77        if b & 0x80 == 0 {
78            break;
79        }
80    }
81    Some((value, i))
82}
83
84#[cfg(test)]
85mod tests {
86    use super::*;
87
88    /// RFC 7541 §5.1 示例：前缀 5-bit，值 10 → 单字节 `0x0A`
89    #[test]
90    fn decode_small_single_byte() {
91        assert_eq!(decode_prefix_integer(&[0x0A], 5), Some((10, 1)));
92        assert_eq!(decode_prefix_integer(&[0x0A], 8), Some((10, 1)));
93    }
94
95    /// 8-bit 前缀整体作为值
96    #[test]
97    fn decode_max_prefix() {
98        assert_eq!(decode_prefix_integer(&[0x2A], 8), Some((42, 1)));
99    }
100
101    /// 1337 = 31 + 26 + 10*2^7（5-bit 前缀三字节）
102    #[test]
103    fn decode_multi_byte() {
104        let data = [0x1F, 0x9A, 0x0A];
105        assert_eq!(decode_prefix_integer(&data, 5), Some((1337, 3)));
106    }
107
108    #[test]
109    fn decode_empty_rejected() {
110        assert_eq!(decode_prefix_integer(&[], 5), None);
111        assert_eq!(decode_prefix_integer(&[0x00], 0), None);
112        assert_eq!(decode_prefix_integer(&[0x00], 9), None);
113    }
114
115    /// 超长扩展字节（超过 u64 位移上限）fail-closed
116    #[test]
117    fn decode_overflow_rejected() {
118        let data = [0x1F, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x01];
119        assert_eq!(decode_prefix_integer(&data, 5), None);
120    }
121
122    /// 无终止字节（全 0xFF 延续）fail-closed，不 panic / 不死循环
123    #[test]
124    fn decode_never_terminating_rejected() {
125        assert_eq!(decode_prefix_integer(&[0xFF; 16], 7), None);
126    }
127
128    /// 截断输入 fail-closed
129    #[test]
130    fn decode_truncated_rejected() {
131        assert_eq!(decode_prefix_integer(&[0xFF], 7), None);
132    }
133
134    /// 编码/解码往返一致性（含 u64 大值）
135    #[test]
136    fn encode_decode_roundtrip() {
137        let cases: &[(u64, u8, u8)] = &[
138            (5, 7, 0x00),
139            (10, 5, 0x00),
140            (127, 7, 0x00),
141            (128, 7, 0x00),
142            (1337, 7, 0x00),
143            (65535, 7, 0x00),
144            (u32::MAX as u64, 7, 0x00),
145            // 最大可解码值：需 shift 56（bit 62），超过需 shift 63 的值（如 u64::MAX）
146            // 会被 `m > 56` 防线拒绝（与 QPACK 原始 fail-closed 语义一致）。
147            (i64::MAX as u64, 7, 0x00),
148            (42, 8, 0x00),
149            (1, 4, 0x10),
150            (2, 6, 0x40),
151            (3, 6, 0x80),
152        ];
153        for &(value, prefix_bits, pattern) in cases {
154            let mut out = Vec::new();
155            encode_prefix_integer(&mut out, value, prefix_bits, pattern);
156            let (decoded, consumed) = decode_prefix_integer(&out, prefix_bits).unwrap();
157            assert_eq!(decoded, value, "value {value} (prefix {prefix_bits})");
158            assert_eq!(consumed, out.len());
159        }
160    }
161
162    /// 前缀模式位保留在首字节高位
163    #[test]
164    fn encode_preserves_prefix_pattern() {
165        let mut out = Vec::new();
166        encode_prefix_integer(&mut out, 5, 7, 0x80);
167        assert_eq!(out, vec![0x85]); // 0x80 | 5
168        let mut out = Vec::new();
169        encode_prefix_integer(&mut out, 1, 6, 0x40);
170        assert_eq!(out, vec![0x41]); // 0x40 | 1
171    }
172}
zenith_foundation/prefix_int.rs

zenith_foundation/
prefix_int.rs
