Skip to main content

yang_pcg/export/binary/
mod.rs

1// 二进制导出与导入模块
2// 提供紧凑的二进制格式导出/导入功能,包含 magic 标识、版本头、CRC32 校验和
3//
4// 二进制格式布局:
5// - Bytes 0-3:   Magic 标识 "YPCG"
6// - Bytes 4-5:   Schema 主版本号 (u16 LE)
7// - Bytes 6-7:   Schema 次版本号 (u16 LE)
8// - Bytes 8-11:  保留字段(用于未来扩展,当前填充 0)
9// - Bytes 12-15: Body 长度 (u32 LE)
10// - Bytes 16..16+body_len: 紧凑 JSON 编码的 body 数据
11// - 最后 4 字节:  CRC32 校验和(覆盖前面所有字节)
12
13use crate::error::{PcgError, PcgResult};
14use crate::export::CURRENT_SCHEMA_VERSION;
15use crate::model::result::GenerationResult;
16
17/// 二进制格式的 Magic 标识
18const BINARY_MAGIC: &[u8; 4] = b"YPCG";
19
20/// 文件头固定长度(magic + version + reserved + body_length)
21const HEADER_SIZE: usize = 16;
22
23/// CRC32 校验和长度
24const CRC32_SIZE: usize = 4;
25
26/// 最小有效文件大小(header + 至少 1 字节 body + crc32)
27const MIN_FILE_SIZE: usize = HEADER_SIZE + 1 + CRC32_SIZE;
28
29/// 将生成结果导出为二进制格式
30///
31/// 使用紧凑的二进制布局,包含 magic 标识、版本头、保留字段、
32/// 紧凑 JSON 编码的 body 数据和 CRC32 校验和。
33///
34/// # 参数
35///
36/// * `result` - 生成结果的引用
37///
38/// # 返回值
39///
40/// 成功时返回二进制数据的字节向量,失败时返回导出错误。
41///
42/// # 格式布局
43///
44/// | 偏移 | 长度 | 内容 |
45/// |------|------|------|
46/// | 0-3 | 4 | Magic "YPCG" |
47/// | 4-5 | 2 | Schema 主版本号 (u16 LE) |
48/// | 6-7 | 2 | Schema 次版本号 (u16 LE) |
49/// | 8-11 | 4 | 保留字段 (全零) |
50/// | 12-15 | 4 | Body 长度 (u32 LE) |
51/// | 16..16+N | N | 紧凑 JSON 编码的 body |
52/// | 最后 4 字节 | 4 | CRC32 校验和 |
53///
54/// # 示例
55///
56/// ```rust,ignore
57/// use yang_pcg::export::binary::export_binary;
58///
59/// let result = generator.generate(request)?;
60/// let bytes = export_binary(&result)?;
61/// std::fs::write("output.ypcg", &bytes)?;
62/// ```
63pub fn export_binary(result: &GenerationResult) -> PcgResult<Vec<u8>> {
64    // 使用紧凑 JSON 作为 body 编码
65    // bincode 不支持 skip_serializing_if 等 serde 属性,
66    // 因此使用 JSON 字节作为 body,保证完全兼容性。
67    // 二进制格式的价值在于结构化头部和 CRC32 校验和。
68    let body = serde_json::to_vec(result)
69        .map_err(|e| PcgError::export_err(format!("二进制序列化失败: {}", e), "binary", e))?;
70
71    let body_len = body.len();
72
73    // 检查 body 长度是否超过 u32 最大值
74    if body_len > u32::MAX as usize {
75        return Err(PcgError::export_with_format(
76            format!("数据体过大,超过 4GB 限制: {} 字节", body_len),
77            "binary",
78            None,
79        ));
80    }
81
82    // 解析当前 schema 版本号
83    let (major, minor) = parse_schema_version(CURRENT_SCHEMA_VERSION)?;
84
85    // 组装二进制数据
86    let total_size = HEADER_SIZE + body_len + CRC32_SIZE;
87    let mut buffer = Vec::with_capacity(total_size);
88
89    // 写入 Magic 标识
90    buffer.extend_from_slice(BINARY_MAGIC);
91
92    // 写入 Schema 版本号(小端序)
93    buffer.extend_from_slice(&major.to_le_bytes());
94    buffer.extend_from_slice(&minor.to_le_bytes());
95
96    // 写入保留字段(4 字节全零,用于未来扩展)
97    buffer.extend_from_slice(&[0u8; 4]);
98
99    // 写入 Body 长度(小端序)
100    buffer.extend_from_slice(&(body_len as u32).to_le_bytes());
101
102    // 写入 Body 数据
103    buffer.extend_from_slice(&body);
104
105    // 计算并写入 CRC32 校验和(覆盖前面所有字节)
106    let crc = crc32fast::hash(&buffer);
107    buffer.extend_from_slice(&crc.to_le_bytes());
108
109    Ok(buffer)
110}
111
112/// 从二进制数据导入生成结果
113///
114/// 验证 magic 标识、版本兼容性和 CRC32 校验和,然后反序列化 body 数据。
115///
116/// # 参数
117///
118/// * `data` - 二进制数据的字节切片
119///
120/// # 返回值
121///
122/// 成功时返回重建的 `GenerationResult`,失败时返回相应错误。
123///
124/// # 错误情况
125///
126/// - 数据长度不足(小于最小有效大小)
127/// - Magic 标识不匹配
128/// - Schema 主版本号不兼容
129/// - CRC32 校验和不匹配(数据损坏)
130/// - Body 反序列化失败
131///
132/// # 示例
133///
134/// ```rust,ignore
135/// use yang_pcg::export::binary::import_binary;
136///
137/// let bytes = std::fs::read("output.ypcg")?;
138/// let result = import_binary(&bytes)?;
139/// println!("种子: {}", result.metadata.seed);
140/// ```
141pub fn import_binary(data: &[u8]) -> PcgResult<GenerationResult> {
142    // 检查最小数据长度
143    if data.len() < MIN_FILE_SIZE {
144        return Err(PcgError::corrupted_data_with_type(
145            format!(
146                "数据长度不足: 期望至少 {} 字节,实际 {} 字节",
147                MIN_FILE_SIZE,
148                data.len()
149            ),
150            "binary",
151        ));
152    }
153
154    // 验证 Magic 标识
155    let magic = &data[0..4];
156    if magic != BINARY_MAGIC {
157        return Err(PcgError::corrupted_data_with_type(
158            format!(
159                "Magic 标识不匹配: 期望 {:?},实际 {:?}",
160                BINARY_MAGIC, magic
161            ),
162            "binary",
163        ));
164    }
165
166    // 读取版本号
167    let file_major = u16::from_le_bytes([data[4], data[5]]);
168    let _file_minor = u16::from_le_bytes([data[6], data[7]]);
169
170    // 验证主版本号兼容性
171    let (current_major, _current_minor) = parse_schema_version(CURRENT_SCHEMA_VERSION)?;
172    if file_major != current_major {
173        return Err(PcgError::corrupted_data_with_version(
174            format!(
175                "Schema 主版本号不兼容: 文件版本 {},当前版本 {}",
176                file_major, current_major
177            ),
178            "binary",
179            &format!("{}", current_major),
180            &format!("{}", file_major),
181        ));
182    }
183
184    // 读取保留字段(当前忽略,用于未来扩展)
185    // data[8..12] 为保留字段
186
187    // 读取 Body 长度
188    let body_len = u32::from_le_bytes([data[12], data[13], data[14], data[15]]) as usize;
189
190    // 验证数据总长度是否匹配
191    let expected_total = HEADER_SIZE + body_len + CRC32_SIZE;
192    if data.len() != expected_total {
193        return Err(PcgError::corrupted_data_with_type(
194            format!(
195                "数据长度不匹配: 头部声明 body 长度 {},期望总长度 {},实际总长度 {}",
196                body_len,
197                expected_total,
198                data.len()
199            ),
200            "binary",
201        ));
202    }
203
204    // 验证 CRC32 校验和
205    let payload = &data[..data.len() - CRC32_SIZE];
206    let stored_crc = u32::from_le_bytes([
207        data[data.len() - 4],
208        data[data.len() - 3],
209        data[data.len() - 2],
210        data[data.len() - 1],
211    ]);
212    let computed_crc = crc32fast::hash(payload);
213
214    if stored_crc != computed_crc {
215        return Err(PcgError::corrupted_data_with_type(
216            format!(
217                "CRC32 校验和不匹配: 存储值 0x{:08X},计算值 0x{:08X},数据可能已损坏",
218                stored_crc, computed_crc
219            ),
220            "binary",
221        ));
222    }
223
224    // 反序列化 Body(从紧凑 JSON 字节解码)
225    let body = &data[HEADER_SIZE..HEADER_SIZE + body_len];
226    let result: GenerationResult = serde_json::from_slice(body)
227        .map_err(|e| PcgError::export_err(format!("二进制反序列化失败: {}", e), "binary", e))?;
228
229    result.validate_terrain_data()?;
230    Ok(result)
231}
232
233/// 解析 schema 版本字符串为 (major, minor) 元组
234///
235/// 支持 semver 格式(如 "1.0.0"),提取主版本号和次版本号。
236fn parse_schema_version(version: &str) -> PcgResult<(u16, u16)> {
237    let parts: Vec<&str> = version.split('.').collect();
238    if parts.len() < 2 {
239        return Err(PcgError::export_with_format(
240            format!("无效的版本格式: '{}',期望 semver 格式", version),
241            "binary",
242            None,
243        ));
244    }
245
246    let major = parts[0].parse::<u16>().map_err(|_| {
247        PcgError::export_with_format(format!("无法解析主版本号: '{}'", parts[0]), "binary", None)
248    })?;
249
250    let minor = parts[1].parse::<u16>().map_err(|_| {
251        PcgError::export_with_format(format!("无法解析次版本号: '{}'", parts[1]), "binary", None)
252    })?;
253
254    Ok((major, minor))
255}
256
257#[cfg(test)]
258mod __tests__;