Skip to main content

ionic/ion/
header.rs

1use crate::ion::{
2    ByteRange, IonResult,
3    decoder::decode::INDEX_ENTRY_BYTES,
4    encoder::encode::{CHROM_SUMMARY_SIZE, SPEC_SUMMARY_SIZE},
5    format::{
6        CODEC_ZSTD, CURRENT_VERSION, FILE_SIGNATURE, HEADER_SIZE, allow_compression, allow_version,
7    },
8    meta_groups::{MetaSection, MetaTotals},
9};
10
11const BLOCK_DIRECTORY_ENTRY_SIZE_U64: u64 = 32;
12
13pub const HEADER_FORMAT_VERSION_OFFSET: usize = 9;
14
15pub(crate) const HEADER_CODEC_ID: usize = 11;
16pub(crate) const HEADER_COMPRESSION_LEVEL: usize = 12;
17pub(crate) const HEADER_ARRAY_FILTER_ID: usize = 13;
18pub(crate) const HEADER_TARGET_BLOCK_SIZE: usize = 16;
19pub(crate) const HEADER_TARGET_MZ_WINDOW: usize = 24;
20
21pub(crate) const HEADER_OFFSET_SPEC_WINDOW_DIRECTORY: usize = 32;
22pub(crate) const HEADER_LEN_SPEC_WINDOW_DIRECTORY: usize = 40;
23pub(crate) const HEADER_OFFSET_SPEC_SUMMARY: usize = 48;
24pub(crate) const HEADER_LEN_SPEC_SUMMARY: usize = 56;
25pub(crate) const HEADER_OFFSET_SPEC_ENTRIES: usize = 64;
26pub(crate) const HEADER_LEN_SPEC_ENTRIES: usize = 72;
27pub(crate) const HEADER_OFFSET_SPEC_ARRAY_ADDRESSES: usize = 80;
28pub(crate) const HEADER_LEN_SPEC_ARRAY_ADDRESSES: usize = 88;
29
30pub(crate) const HEADER_OFFSET_CHROM_WINDOW_DIRECTORY: usize = 96;
31pub(crate) const HEADER_LEN_CHROM_WINDOW_DIRECTORY: usize = 104;
32pub(crate) const HEADER_OFFSET_CHROM_SUMMARY: usize = 112;
33pub(crate) const HEADER_LEN_CHROM_SUMMARY: usize = 120;
34pub(crate) const HEADER_OFFSET_CHROM_ENTRIES: usize = 128;
35pub(crate) const HEADER_LEN_CHROM_ENTRIES: usize = 136;
36pub(crate) const HEADER_OFFSET_CHROM_ARRAY_ADDRESSES: usize = 144;
37pub(crate) const HEADER_LEN_CHROM_ARRAY_ADDRESSES: usize = 152;
38
39pub(crate) const HEADER_OFFSET_SPEC_META: usize = 160;
40pub(crate) const HEADER_LEN_SPEC_META: usize = 168;
41pub(crate) const HEADER_OFFSET_CHROM_META: usize = 176;
42pub(crate) const HEADER_LEN_CHROM_META: usize = 184;
43pub(crate) const HEADER_OFFSET_GLOBAL_META: usize = 192;
44pub(crate) const HEADER_LEN_GLOBAL_META: usize = 200;
45
46pub(crate) const HEADER_OFFSET_PACKED_SPECTRA: usize = 208;
47pub(crate) const HEADER_LEN_PACKED_SPECTRA: usize = 216;
48pub(crate) const HEADER_OFFSET_PACKED_CHROMS: usize = 224;
49pub(crate) const HEADER_LEN_PACKED_CHROMS: usize = 232;
50
51pub(crate) const HEADER_SPECTRUM_BLOCK_COUNT: usize = 240;
52pub(crate) const HEADER_CHROM_BLOCK_COUNT: usize = 248;
53pub(crate) const HEADER_SPECTRUM_COUNT: usize = 256;
54pub(crate) const HEADER_CHROM_COUNT: usize = 264;
55
56pub(crate) const HEADER_SPEC_ARRAY_TYPE_COUNT: usize = 272;
57pub(crate) const HEADER_CHROM_ARRAY_TYPE_COUNT: usize = 280;
58
59pub(crate) const HEADER_SPEC_META_ROW_COUNT: usize = 288;
60pub(crate) const HEADER_SPEC_META_NUMERIC_COUNT: usize = 296;
61pub(crate) const HEADER_SPEC_META_STRING_COUNT: usize = 304;
62pub(crate) const HEADER_CHROM_META_ROW_COUNT: usize = 312;
63pub(crate) const HEADER_CHROM_META_NUMERIC_COUNT: usize = 320;
64pub(crate) const HEADER_CHROM_META_STRING_COUNT: usize = 328;
65pub(crate) const HEADER_GLOBAL_META_ROW_COUNT: usize = 336;
66pub(crate) const HEADER_GLOBAL_META_NUMERIC_COUNT: usize = 344;
67pub(crate) const HEADER_GLOBAL_META_STRING_COUNT: usize = 352;
68
69pub(crate) const HEADER_SPEC_META_UNCOMPRESSED_SIZE: usize = 360;
70pub(crate) const HEADER_CHROM_META_UNCOMPRESSED_SIZE: usize = 368;
71pub(crate) const HEADER_GLOBAL_META_UNCOMPRESSED_SIZE: usize = 376;
72
73pub(crate) const HEADER_PLAIN_LEN_SPEC_WINDOW_DIRECTORY: usize = 384;
74pub(crate) const HEADER_PLAIN_LEN_CHROM_WINDOW_DIRECTORY: usize = 392;
75
76pub(crate) const HEADER_TOTAL_FILE_SIZE: usize = 400;
77pub(crate) const HEADER_META_GROUP_SIZE: usize = 408;
78pub(crate) const HEADER_SPEC_META_GROUP_COUNT: usize = 416;
79pub(crate) const HEADER_CHROM_META_GROUP_COUNT: usize = 424;
80
81pub(crate) const RESERVED_BLOCK_START: usize = 432;
82pub(crate) const RESERVED_BLOCK_SIZE: usize = 536;
83
84pub(crate) const HEADER_SPEC_WINDOW_DIRECTORY_CRC32: usize = 968;
85pub(crate) const HEADER_SPEC_SUMMARY_CRC32: usize = 972;
86pub(crate) const HEADER_SPEC_ENTRIES_CRC32: usize = 976;
87pub(crate) const HEADER_SPEC_ARRAY_ADDRESSES_CRC32: usize = 980;
88pub(crate) const HEADER_CHROM_WINDOW_DIRECTORY_CRC32: usize = 984;
89pub(crate) const HEADER_CHROM_SUMMARY_CRC32: usize = 988;
90pub(crate) const HEADER_CHROM_ENTRIES_CRC32: usize = 992;
91pub(crate) const HEADER_CHROM_ARRAY_ADDRESSES_CRC32: usize = 996;
92pub(crate) const HEADER_SPEC_DIRECTORY_CRC32: usize = 1000;
93pub(crate) const HEADER_CHROM_DIRECTORY_CRC32: usize = 1004;
94pub(crate) const HEADER_SPEC_META_CRC32: usize = 1008;
95pub(crate) const HEADER_CHROM_META_CRC32: usize = 1012;
96pub(crate) const HEADER_GLOBAL_META_CRC32: usize = 1016;
97pub(crate) const HEADER_CRC32: usize = 1020;
98
99const _: () = assert!(HEADER_TARGET_MZ_WINDOW == 24);
100const _: () = assert!(HEADER_OFFSET_SPEC_WINDOW_DIRECTORY == 32);
101const _: () = assert!(HEADER_OFFSET_SPEC_SUMMARY == 48);
102const _: () = assert!(HEADER_OFFSET_SPEC_ENTRIES == 64);
103const _: () = assert!(HEADER_OFFSET_SPEC_ARRAY_ADDRESSES == 80);
104const _: () = assert!(HEADER_OFFSET_CHROM_WINDOW_DIRECTORY == 96);
105const _: () = assert!(HEADER_OFFSET_CHROM_SUMMARY == 112);
106const _: () = assert!(HEADER_OFFSET_CHROM_ENTRIES == 128);
107const _: () = assert!(HEADER_OFFSET_CHROM_ARRAY_ADDRESSES == 144);
108const _: () = assert!(HEADER_PLAIN_LEN_SPEC_WINDOW_DIRECTORY == 384);
109const _: () = assert!(HEADER_PLAIN_LEN_CHROM_WINDOW_DIRECTORY == 392);
110const _: () = assert!(RESERVED_BLOCK_START == 432);
111const _: () = assert!(RESERVED_BLOCK_SIZE == 536);
112const _: () = assert!(RESERVED_BLOCK_START + RESERVED_BLOCK_SIZE == 968);
113const _: () = assert!(HEADER_SPEC_WINDOW_DIRECTORY_CRC32 == 968);
114const _: () = assert!(HEADER_SPEC_SUMMARY_CRC32 == 972);
115const _: () = assert!(HEADER_SPEC_ENTRIES_CRC32 == 976);
116const _: () = assert!(HEADER_SPEC_ARRAY_ADDRESSES_CRC32 == 980);
117const _: () = assert!(HEADER_CHROM_WINDOW_DIRECTORY_CRC32 == 984);
118const _: () = assert!(HEADER_CHROM_SUMMARY_CRC32 == 988);
119const _: () = assert!(HEADER_CHROM_ENTRIES_CRC32 == 992);
120const _: () = assert!(HEADER_CHROM_ARRAY_ADDRESSES_CRC32 == 996);
121const _: () = assert!(HEADER_SPEC_DIRECTORY_CRC32 == 1000);
122const _: () = assert!(HEADER_CHROM_DIRECTORY_CRC32 == 1004);
123const _: () = assert!(HEADER_SPEC_META_CRC32 == 1008);
124const _: () = assert!(HEADER_CHROM_META_CRC32 == 1012);
125const _: () = assert!(HEADER_GLOBAL_META_CRC32 == 1016);
126const _: () = assert!(HEADER_CRC32 == 1020);
127
128#[derive(Debug, Clone, Default)]
129pub(crate) struct Header {
130    pub(crate) format_version: u16,
131    pub(crate) compression_codec: u8,
132    pub(crate) compression_level: u8,
133    pub(crate) default_array_filter: u8,
134    pub(crate) target_block_uncompressed_bytes: u64,
135    pub(crate) off_spec_summary: u64,
136    pub(crate) len_spec_summary: u64,
137    pub(crate) off_chrom_summary: u64,
138    pub(crate) len_chrom_summary: u64,
139    pub(crate) off_spec_entries: u64,
140    pub(crate) len_spec_entries: u64,
141    pub(crate) off_spec_array_addresses: u64,
142    pub(crate) len_spec_array_addresses: u64,
143    pub(crate) off_chrom_entries: u64,
144    pub(crate) len_chrom_entries: u64,
145    pub(crate) off_chrom_array_addresses: u64,
146    pub(crate) len_chrom_array_addresses: u64,
147    pub(crate) off_spec_meta: u64,
148    pub(crate) len_spec_meta: u64,
149    pub(crate) off_chrom_meta: u64,
150    pub(crate) len_chrom_meta: u64,
151    pub(crate) off_global_meta: u64,
152    pub(crate) len_global_meta: u64,
153    pub(crate) off_spec_container: u64,
154    pub(crate) len_spec_container: u64,
155    pub(crate) off_chrom_container: u64,
156    pub(crate) len_chrom_container: u64,
157    pub(crate) spec_block_count: u64,
158    pub(crate) chrom_block_count: u64,
159    pub(crate) spectrum_count: u64,
160    pub(crate) chrom_count: u64,
161    pub(crate) spec_meta_count: u64,
162    pub(crate) spec_meta_numeric_count: u64,
163    pub(crate) spec_meta_string_count: u64,
164    pub(crate) chrom_meta_count: u64,
165    pub(crate) chrom_meta_numeric_count: u64,
166    pub(crate) chrom_meta_string_count: u64,
167    pub(crate) global_meta_count: u64,
168    pub(crate) global_meta_numeric_count: u64,
169    pub(crate) global_meta_string_count: u64,
170    pub(crate) spec_array_type_count: u64,
171    pub(crate) chrom_array_type_count: u64,
172    pub(crate) spec_meta_uncompressed_bytes: u64,
173    pub(crate) chrom_meta_uncompressed_bytes: u64,
174    pub(crate) global_meta_uncompressed_bytes: u64,
175    pub(crate) total_file_size: u64,
176    pub(crate) meta_group_size: u32,
177    pub(crate) spec_meta_group_count: u64,
178    pub(crate) chrom_meta_group_count: u64,
179    pub(crate) spec_summary_crc32: u32,
180    pub(crate) spec_entries_crc32: u32,
181    pub(crate) spec_array_addresses_crc32: u32,
182    pub(crate) chrom_summary_crc32: u32,
183    pub(crate) chrom_entries_crc32: u32,
184    pub(crate) chrom_array_addresses_crc32: u32,
185    pub(crate) target_mz_window: u32,
186    pub(crate) spec_directory_crc32: u32,
187    pub(crate) chrom_directory_crc32: u32,
188    pub(crate) off_spec_window_directory: u64,
189    pub(crate) len_spec_window_directory: u64,
190    pub(crate) off_chrom_window_directory: u64,
191    pub(crate) len_chrom_window_directory: u64,
192    pub(crate) plain_len_spec_window_directory: u64,
193    pub(crate) plain_len_chrom_window_directory: u64,
194    pub(crate) spec_window_directory_crc32: u32,
195    pub(crate) chrom_window_directory_crc32: u32,
196    pub(crate) spec_meta_crc32: u32,
197    pub(crate) chrom_meta_crc32: u32,
198    pub(crate) global_meta_crc32: u32,
199    pub(crate) header_crc32: u32,
200}
201
202impl Header {
203    pub(crate) fn parse(bytes: &[u8]) -> IonResult<Self> {
204        if bytes.len() < HEADER_SIZE {
205            return Err("header: file too small".into());
206        }
207
208        let h = &bytes[..HEADER_SIZE];
209
210        if h[0..8] != FILE_SIGNATURE {
211            return Err("header: invalid file signature".into());
212        }
213        if h[8] != 0 {
214            return Err("header: expected little-endian endianness_flag=0".into());
215        }
216
217        let format_version = version_of(bytes).unwrap();
218        allow_version(format_version)?;
219        let compression_codec = h[HEADER_CODEC_ID];
220        let compression_level = h[HEADER_COMPRESSION_LEVEL];
221        allow_compression(compression_codec, compression_level)?;
222        let default_array_filter = h[HEADER_ARRAY_FILTER_ID];
223
224        if h[14] != 0 || h[15] != 0 {
225            return Err("header: reserved bytes at 14..16 must be zero".into());
226        }
227
228        let target_block_uncompressed_bytes = read_u64_at(h, HEADER_TARGET_BLOCK_SIZE);
229
230        let off_spec_entries = read_u64_at(h, HEADER_OFFSET_SPEC_ENTRIES);
231        let len_spec_entries = read_u64_at(h, HEADER_LEN_SPEC_ENTRIES);
232        let off_spec_array_addresses = read_u64_at(h, HEADER_OFFSET_SPEC_ARRAY_ADDRESSES);
233        let len_spec_array_addresses = read_u64_at(h, HEADER_LEN_SPEC_ARRAY_ADDRESSES);
234        let off_chrom_entries = read_u64_at(h, HEADER_OFFSET_CHROM_ENTRIES);
235        let len_chrom_entries = read_u64_at(h, HEADER_LEN_CHROM_ENTRIES);
236        let off_chrom_array_addresses = read_u64_at(h, HEADER_OFFSET_CHROM_ARRAY_ADDRESSES);
237        let len_chrom_array_addresses = read_u64_at(h, HEADER_LEN_CHROM_ARRAY_ADDRESSES);
238        let off_spec_meta = read_u64_at(h, HEADER_OFFSET_SPEC_META);
239        let len_spec_meta = read_u64_at(h, HEADER_LEN_SPEC_META);
240        let off_chrom_meta = read_u64_at(h, HEADER_OFFSET_CHROM_META);
241        let len_chrom_meta = read_u64_at(h, HEADER_LEN_CHROM_META);
242        let off_global_meta = read_u64_at(h, HEADER_OFFSET_GLOBAL_META);
243        let len_global_meta = read_u64_at(h, HEADER_LEN_GLOBAL_META);
244        let off_spec_container = read_u64_at(h, HEADER_OFFSET_PACKED_SPECTRA);
245        let len_spec_container = read_u64_at(h, HEADER_LEN_PACKED_SPECTRA);
246        let off_chrom_container = read_u64_at(h, HEADER_OFFSET_PACKED_CHROMS);
247        let len_chrom_container = read_u64_at(h, HEADER_LEN_PACKED_CHROMS);
248
249        let spec_block_count = read_u64_at(h, HEADER_SPECTRUM_BLOCK_COUNT);
250        let chrom_block_count = read_u64_at(h, HEADER_CHROM_BLOCK_COUNT);
251        let spectrum_count = read_u64_at(h, HEADER_SPECTRUM_COUNT);
252        let chrom_count = read_u64_at(h, HEADER_CHROM_COUNT);
253
254        let spec_meta_count = read_u64_at(h, HEADER_SPEC_META_ROW_COUNT);
255        let spec_meta_numeric_count = read_u64_at(h, HEADER_SPEC_META_NUMERIC_COUNT);
256        let spec_meta_string_count = read_u64_at(h, HEADER_SPEC_META_STRING_COUNT);
257        let chrom_meta_count = read_u64_at(h, HEADER_CHROM_META_ROW_COUNT);
258        let chrom_meta_numeric_count = read_u64_at(h, HEADER_CHROM_META_NUMERIC_COUNT);
259        let chrom_meta_string_count = read_u64_at(h, HEADER_CHROM_META_STRING_COUNT);
260        let global_meta_count = read_u64_at(h, HEADER_GLOBAL_META_ROW_COUNT);
261        let global_meta_numeric_count = read_u64_at(h, HEADER_GLOBAL_META_NUMERIC_COUNT);
262        let global_meta_string_count = read_u64_at(h, HEADER_GLOBAL_META_STRING_COUNT);
263        let spec_array_type_count = read_u64_at(h, HEADER_SPEC_ARRAY_TYPE_COUNT);
264        let chrom_array_type_count = read_u64_at(h, HEADER_CHROM_ARRAY_TYPE_COUNT);
265
266        let spec_meta_uncompressed_bytes = read_u64_at(h, HEADER_SPEC_META_UNCOMPRESSED_SIZE);
267        let chrom_meta_uncompressed_bytes = read_u64_at(h, HEADER_CHROM_META_UNCOMPRESSED_SIZE);
268        let global_meta_uncompressed_bytes = read_u64_at(h, HEADER_GLOBAL_META_UNCOMPRESSED_SIZE);
269
270        let off_spec_summary = read_u64_at(h, HEADER_OFFSET_SPEC_SUMMARY);
271        let len_spec_summary = read_u64_at(h, HEADER_LEN_SPEC_SUMMARY);
272        let off_chrom_summary = read_u64_at(h, HEADER_OFFSET_CHROM_SUMMARY);
273        let len_chrom_summary = read_u64_at(h, HEADER_LEN_CHROM_SUMMARY);
274        let total_file_size = read_u64_at(h, HEADER_TOTAL_FILE_SIZE);
275
276        let meta_group_size_stored = read_u64_at(h, HEADER_META_GROUP_SIZE);
277        if meta_group_size_stored > u32::MAX as u64 {
278            return Err("header: meta_group_size exceeds u32 range".into());
279        }
280        let meta_group_size = meta_group_size_stored as u32;
281        let spec_meta_group_count = read_u64_at(h, HEADER_SPEC_META_GROUP_COUNT);
282        let chrom_meta_group_count = read_u64_at(h, HEADER_CHROM_META_GROUP_COUNT);
283
284        let off_spec_window_directory = read_u64_at(h, HEADER_OFFSET_SPEC_WINDOW_DIRECTORY);
285        let len_spec_window_directory = read_u64_at(h, HEADER_LEN_SPEC_WINDOW_DIRECTORY);
286        let off_chrom_window_directory = read_u64_at(h, HEADER_OFFSET_CHROM_WINDOW_DIRECTORY);
287        let len_chrom_window_directory = read_u64_at(h, HEADER_LEN_CHROM_WINDOW_DIRECTORY);
288        let spec_window_directory_crc32 = read_u32_at(h, HEADER_SPEC_WINDOW_DIRECTORY_CRC32);
289        let chrom_window_directory_crc32 = read_u32_at(h, HEADER_CHROM_WINDOW_DIRECTORY_CRC32);
290
291        let plain_len_spec_window_directory =
292            read_u64_at(h, HEADER_PLAIN_LEN_SPEC_WINDOW_DIRECTORY);
293        let plain_len_chrom_window_directory =
294            read_u64_at(h, HEADER_PLAIN_LEN_CHROM_WINDOW_DIRECTORY);
295
296        let spec_summary_crc32 = read_u32_at(h, HEADER_SPEC_SUMMARY_CRC32);
297        let spec_entries_crc32 = read_u32_at(h, HEADER_SPEC_ENTRIES_CRC32);
298        let spec_array_addresses_crc32 = read_u32_at(h, HEADER_SPEC_ARRAY_ADDRESSES_CRC32);
299        let chrom_summary_crc32 = read_u32_at(h, HEADER_CHROM_SUMMARY_CRC32);
300        let chrom_entries_crc32 = read_u32_at(h, HEADER_CHROM_ENTRIES_CRC32);
301        let chrom_array_addresses_crc32 = read_u32_at(h, HEADER_CHROM_ARRAY_ADDRESSES_CRC32);
302
303        let target_mz_window = read_u32_at(h, HEADER_TARGET_MZ_WINDOW);
304
305        if h[RESERVED_BLOCK_START..RESERVED_BLOCK_START + RESERVED_BLOCK_SIZE]
306            .iter()
307            .any(|&b| b != 0)
308        {
309            return Err("header: reserved block 432..968 must be all zeros".into());
310        }
311
312        let spec_directory_crc32 = read_u32_at(h, HEADER_SPEC_DIRECTORY_CRC32);
313        let chrom_directory_crc32 = read_u32_at(h, HEADER_CHROM_DIRECTORY_CRC32);
314        let spec_meta_crc32 = read_u32_at(h, HEADER_SPEC_META_CRC32);
315        let chrom_meta_crc32 = read_u32_at(h, HEADER_CHROM_META_CRC32);
316        let global_meta_crc32 = read_u32_at(h, HEADER_GLOBAL_META_CRC32);
317        let header_crc32 = read_u32_at(h, HEADER_CRC32);
318
319        let header = Header {
320            format_version,
321            compression_codec,
322            compression_level,
323            default_array_filter,
324            target_block_uncompressed_bytes,
325            off_spec_entries,
326            len_spec_entries,
327            off_spec_array_addresses,
328            len_spec_array_addresses,
329            off_chrom_entries,
330            len_chrom_entries,
331            off_chrom_array_addresses,
332            len_chrom_array_addresses,
333            off_spec_meta,
334            len_spec_meta,
335            off_chrom_meta,
336            len_chrom_meta,
337            off_global_meta,
338            len_global_meta,
339            off_spec_container,
340            len_spec_container,
341            off_chrom_container,
342            len_chrom_container,
343            spec_block_count,
344            chrom_block_count,
345            spectrum_count,
346            chrom_count,
347            spec_meta_count,
348            spec_meta_numeric_count,
349            spec_meta_string_count,
350            chrom_meta_count,
351            chrom_meta_numeric_count,
352            chrom_meta_string_count,
353            global_meta_count,
354            global_meta_numeric_count,
355            global_meta_string_count,
356            spec_array_type_count,
357            chrom_array_type_count,
358            spec_meta_uncompressed_bytes,
359            chrom_meta_uncompressed_bytes,
360            global_meta_uncompressed_bytes,
361            off_spec_summary,
362            len_spec_summary,
363            off_chrom_summary,
364            len_chrom_summary,
365            total_file_size,
366            meta_group_size,
367            spec_meta_group_count,
368            chrom_meta_group_count,
369            spec_summary_crc32,
370            spec_entries_crc32,
371            spec_array_addresses_crc32,
372            chrom_summary_crc32,
373            chrom_entries_crc32,
374            chrom_array_addresses_crc32,
375            target_mz_window,
376            spec_directory_crc32,
377            chrom_directory_crc32,
378            off_spec_window_directory,
379            len_spec_window_directory,
380            off_chrom_window_directory,
381            len_chrom_window_directory,
382            plain_len_spec_window_directory,
383            plain_len_chrom_window_directory,
384            spec_window_directory_crc32,
385            chrom_window_directory_crc32,
386            spec_meta_crc32,
387            chrom_meta_crc32,
388            global_meta_crc32,
389            header_crc32,
390        };
391
392        let computed_header_crc = crc32fast::hash(&h[0..HEADER_CRC32]);
393        if computed_header_crc != header.header_crc32 {
394            return Err(format!(
395                "header: header_crc32 mismatch (stored={:#010x}, computed={:#010x})",
396                header.header_crc32, computed_header_crc
397            )
398            .into());
399        }
400
401        Ok(header)
402    }
403
404    pub(crate) fn spec_meta_section(&self) -> MetaSection {
405        MetaSection {
406            range: ByteRange {
407                offset: self.off_spec_meta,
408                length: self.len_spec_meta,
409            },
410            group_count: self.spec_meta_group_count,
411            group_size: self.meta_group_size,
412            item_count: self.spectrum_count,
413            totals: MetaTotals {
414                rows: self.spec_meta_count,
415                numeric: self.spec_meta_numeric_count,
416                string: self.spec_meta_string_count,
417                uncompressed: self.spec_meta_uncompressed_bytes,
418            },
419        }
420    }
421
422    pub(crate) fn chrom_meta_section(&self) -> MetaSection {
423        MetaSection {
424            range: ByteRange {
425                offset: self.off_chrom_meta,
426                length: self.len_chrom_meta,
427            },
428            group_count: self.chrom_meta_group_count,
429            group_size: self.meta_group_size,
430            item_count: self.chrom_count,
431            totals: MetaTotals {
432                rows: self.chrom_meta_count,
433                numeric: self.chrom_meta_numeric_count,
434                string: self.chrom_meta_string_count,
435                uncompressed: self.chrom_meta_uncompressed_bytes,
436            },
437        }
438    }
439
440    pub(crate) fn write(&self, buf: &mut [u8]) {
441        buf[0..FILE_SIGNATURE.len()].copy_from_slice(&FILE_SIGNATURE);
442        buf[8] = 0u8;
443        write_u16_at(
444            buf,
445            HEADER_FORMAT_VERSION_OFFSET,
446            crate::ion::format::CURRENT_VERSION,
447        );
448
449        write_u8_at(buf, HEADER_CODEC_ID, self.compression_codec);
450        write_u8_at(buf, HEADER_COMPRESSION_LEVEL, self.compression_level);
451        write_u8_at(buf, HEADER_ARRAY_FILTER_ID, self.default_array_filter);
452
453        write_u64_at(
454            buf,
455            HEADER_TARGET_BLOCK_SIZE,
456            self.target_block_uncompressed_bytes,
457        );
458
459        write_u64_at(buf, HEADER_OFFSET_SPEC_ENTRIES, self.off_spec_entries);
460        write_u64_at(buf, HEADER_LEN_SPEC_ENTRIES, self.len_spec_entries);
461        write_u64_at(
462            buf,
463            HEADER_OFFSET_SPEC_ARRAY_ADDRESSES,
464            self.off_spec_array_addresses,
465        );
466        write_u64_at(
467            buf,
468            HEADER_LEN_SPEC_ARRAY_ADDRESSES,
469            self.len_spec_array_addresses,
470        );
471        write_u64_at(buf, HEADER_OFFSET_CHROM_ENTRIES, self.off_chrom_entries);
472        write_u64_at(buf, HEADER_LEN_CHROM_ENTRIES, self.len_chrom_entries);
473        write_u64_at(
474            buf,
475            HEADER_OFFSET_CHROM_ARRAY_ADDRESSES,
476            self.off_chrom_array_addresses,
477        );
478        write_u64_at(
479            buf,
480            HEADER_LEN_CHROM_ARRAY_ADDRESSES,
481            self.len_chrom_array_addresses,
482        );
483        write_u64_at(buf, HEADER_OFFSET_SPEC_META, self.off_spec_meta);
484        write_u64_at(buf, HEADER_LEN_SPEC_META, self.len_spec_meta);
485        write_u64_at(buf, HEADER_OFFSET_CHROM_META, self.off_chrom_meta);
486        write_u64_at(buf, HEADER_LEN_CHROM_META, self.len_chrom_meta);
487        write_u64_at(buf, HEADER_OFFSET_GLOBAL_META, self.off_global_meta);
488        write_u64_at(buf, HEADER_LEN_GLOBAL_META, self.len_global_meta);
489        write_u64_at(buf, HEADER_OFFSET_PACKED_SPECTRA, self.off_spec_container);
490        write_u64_at(buf, HEADER_LEN_PACKED_SPECTRA, self.len_spec_container);
491        write_u64_at(buf, HEADER_OFFSET_PACKED_CHROMS, self.off_chrom_container);
492        write_u64_at(buf, HEADER_LEN_PACKED_CHROMS, self.len_chrom_container);
493
494        write_u64_at(buf, HEADER_SPECTRUM_BLOCK_COUNT, self.spec_block_count);
495        write_u64_at(buf, HEADER_CHROM_BLOCK_COUNT, self.chrom_block_count);
496        write_u64_at(buf, HEADER_SPECTRUM_COUNT, self.spectrum_count);
497        write_u64_at(buf, HEADER_CHROM_COUNT, self.chrom_count);
498        write_u64_at(buf, HEADER_SPEC_META_ROW_COUNT, self.spec_meta_count);
499        write_u64_at(
500            buf,
501            HEADER_SPEC_META_NUMERIC_COUNT,
502            self.spec_meta_numeric_count,
503        );
504        write_u64_at(
505            buf,
506            HEADER_SPEC_META_STRING_COUNT,
507            self.spec_meta_string_count,
508        );
509        write_u64_at(buf, HEADER_CHROM_META_ROW_COUNT, self.chrom_meta_count);
510        write_u64_at(
511            buf,
512            HEADER_CHROM_META_NUMERIC_COUNT,
513            self.chrom_meta_numeric_count,
514        );
515        write_u64_at(
516            buf,
517            HEADER_CHROM_META_STRING_COUNT,
518            self.chrom_meta_string_count,
519        );
520        write_u64_at(buf, HEADER_GLOBAL_META_ROW_COUNT, self.global_meta_count);
521        write_u64_at(
522            buf,
523            HEADER_GLOBAL_META_NUMERIC_COUNT,
524            self.global_meta_numeric_count,
525        );
526        write_u64_at(
527            buf,
528            HEADER_GLOBAL_META_STRING_COUNT,
529            self.global_meta_string_count,
530        );
531        write_u64_at(
532            buf,
533            HEADER_SPEC_ARRAY_TYPE_COUNT,
534            self.spec_array_type_count,
535        );
536        write_u64_at(
537            buf,
538            HEADER_CHROM_ARRAY_TYPE_COUNT,
539            self.chrom_array_type_count,
540        );
541
542        write_u64_at(
543            buf,
544            HEADER_SPEC_META_UNCOMPRESSED_SIZE,
545            self.spec_meta_uncompressed_bytes,
546        );
547        write_u64_at(
548            buf,
549            HEADER_CHROM_META_UNCOMPRESSED_SIZE,
550            self.chrom_meta_uncompressed_bytes,
551        );
552        write_u64_at(
553            buf,
554            HEADER_GLOBAL_META_UNCOMPRESSED_SIZE,
555            self.global_meta_uncompressed_bytes,
556        );
557
558        write_u64_at(buf, HEADER_OFFSET_SPEC_SUMMARY, self.off_spec_summary);
559        write_u64_at(buf, HEADER_LEN_SPEC_SUMMARY, self.len_spec_summary);
560        write_u64_at(buf, HEADER_OFFSET_CHROM_SUMMARY, self.off_chrom_summary);
561        write_u64_at(buf, HEADER_LEN_CHROM_SUMMARY, self.len_chrom_summary);
562
563        write_u64_at(buf, HEADER_TOTAL_FILE_SIZE, self.total_file_size);
564
565        write_u64_at(buf, HEADER_META_GROUP_SIZE, self.meta_group_size as u64);
566        write_u64_at(
567            buf,
568            HEADER_SPEC_META_GROUP_COUNT,
569            self.spec_meta_group_count,
570        );
571        write_u64_at(
572            buf,
573            HEADER_CHROM_META_GROUP_COUNT,
574            self.chrom_meta_group_count,
575        );
576
577        write_u32_at(buf, HEADER_SPEC_SUMMARY_CRC32, self.spec_summary_crc32);
578        write_u32_at(buf, HEADER_SPEC_ENTRIES_CRC32, self.spec_entries_crc32);
579        write_u32_at(
580            buf,
581            HEADER_SPEC_ARRAY_ADDRESSES_CRC32,
582            self.spec_array_addresses_crc32,
583        );
584        write_u32_at(buf, HEADER_CHROM_SUMMARY_CRC32, self.chrom_summary_crc32);
585        write_u32_at(buf, HEADER_CHROM_ENTRIES_CRC32, self.chrom_entries_crc32);
586        write_u32_at(
587            buf,
588            HEADER_CHROM_ARRAY_ADDRESSES_CRC32,
589            self.chrom_array_addresses_crc32,
590        );
591
592        write_u32_at(buf, HEADER_TARGET_MZ_WINDOW, self.target_mz_window);
593
594        write_u32_at(buf, HEADER_SPEC_DIRECTORY_CRC32, self.spec_directory_crc32);
595        write_u32_at(
596            buf,
597            HEADER_CHROM_DIRECTORY_CRC32,
598            self.chrom_directory_crc32,
599        );
600
601        write_u64_at(
602            buf,
603            HEADER_OFFSET_SPEC_WINDOW_DIRECTORY,
604            self.off_spec_window_directory,
605        );
606        write_u64_at(
607            buf,
608            HEADER_LEN_SPEC_WINDOW_DIRECTORY,
609            self.len_spec_window_directory,
610        );
611        write_u64_at(
612            buf,
613            HEADER_OFFSET_CHROM_WINDOW_DIRECTORY,
614            self.off_chrom_window_directory,
615        );
616        write_u64_at(
617            buf,
618            HEADER_LEN_CHROM_WINDOW_DIRECTORY,
619            self.len_chrom_window_directory,
620        );
621        write_u64_at(
622            buf,
623            HEADER_PLAIN_LEN_SPEC_WINDOW_DIRECTORY,
624            self.plain_len_spec_window_directory,
625        );
626        write_u64_at(
627            buf,
628            HEADER_PLAIN_LEN_CHROM_WINDOW_DIRECTORY,
629            self.plain_len_chrom_window_directory,
630        );
631        write_u32_at(
632            buf,
633            HEADER_SPEC_WINDOW_DIRECTORY_CRC32,
634            self.spec_window_directory_crc32,
635        );
636        write_u32_at(
637            buf,
638            HEADER_CHROM_WINDOW_DIRECTORY_CRC32,
639            self.chrom_window_directory_crc32,
640        );
641
642        write_u32_at(buf, HEADER_SPEC_META_CRC32, self.spec_meta_crc32);
643        write_u32_at(buf, HEADER_CHROM_META_CRC32, self.chrom_meta_crc32);
644        write_u32_at(buf, HEADER_GLOBAL_META_CRC32, self.global_meta_crc32);
645        write_u32_at(buf, HEADER_CRC32, self.header_crc32);
646    }
647}
648
649#[inline]
650pub fn version_of(bytes: &[u8]) -> Option<u16> {
651    let end = HEADER_FORMAT_VERSION_OFFSET + 2;
652    if bytes.len() < end {
653        return None;
654    }
655    let mut buf = [0u8; 2];
656    buf.copy_from_slice(&bytes[HEADER_FORMAT_VERSION_OFFSET..end]);
657    Some(u16::from_le_bytes(buf))
658}
659
660pub fn set_version(header: &mut [u8]) -> IonResult<bool> {
661    if header.len() < HEADER_SIZE {
662        return Err(format!(
663            "header: need {HEADER_SIZE} bytes to update the format version, got {}",
664            header.len()
665        )
666        .into());
667    }
668    if header[0..8] != FILE_SIGNATURE {
669        return Err("header: bad file signature".into());
670    }
671    let stored_crc = read_u32_at(header, HEADER_CRC32);
672    let computed_crc = crc32fast::hash(&header[0..HEADER_CRC32]);
673    if stored_crc != computed_crc {
674        return Err(format!(
675            "header: header_crc32 mismatch (stored={stored_crc:#010x}, computed={computed_crc:#010x})"
676        )
677        .into());
678    }
679    let version = version_of(header).unwrap();
680    if version == CURRENT_VERSION {
681        return Ok(false);
682    }
683    allow_version(version)?;
684    write_u16_at(header, HEADER_FORMAT_VERSION_OFFSET, CURRENT_VERSION);
685    let new_crc = crc32fast::hash(&header[0..HEADER_CRC32]);
686    write_u32_at(header, HEADER_CRC32, new_crc);
687    Ok(true)
688}
689
690pub(crate) fn check_section_layout(h: &Header) -> Vec<String> {
691    let mut failures = Vec::new();
692
693    match h.spec_block_count.checked_mul(BLOCK_DIRECTORY_ENTRY_SIZE_U64) {
694        None => failures.push(format!(
695            "condition 5: spec_block_count ({}) × {BLOCK_DIRECTORY_ENTRY_SIZE_U64} overflows u64",
696            h.spec_block_count
697        )),
698        Some(directory_bytes) if directory_bytes > h.len_spec_container => failures.push(format!(
699            "condition 5: spec_block_count × {BLOCK_DIRECTORY_ENTRY_SIZE_U64} ({directory_bytes}) > len_spec_container ({})",
700            h.len_spec_container
701        )),
702        _ => {}
703    }
704
705    match h.chrom_block_count.checked_mul(BLOCK_DIRECTORY_ENTRY_SIZE_U64) {
706        None => failures.push(format!(
707            "condition 6: chrom_block_count ({}) × {BLOCK_DIRECTORY_ENTRY_SIZE_U64} overflows u64",
708            h.chrom_block_count
709        )),
710        Some(directory_bytes) if directory_bytes > h.len_chrom_container => failures.push(format!(
711            "condition 6: chrom_block_count × {BLOCK_DIRECTORY_ENTRY_SIZE_U64} ({directory_bytes}) > len_chrom_container ({})",
712            h.len_chrom_container
713        )),
714        _ => {}
715    }
716
717    let trailer_start = h.total_file_size.saturating_sub(8);
718    let sections: &[(&str, u64, u64)] = &[
719        ("spec_entries", h.off_spec_entries, h.len_spec_entries),
720        (
721            "spec_array_addresses",
722            h.off_spec_array_addresses,
723            h.len_spec_array_addresses,
724        ),
725        ("chrom_entries", h.off_chrom_entries, h.len_chrom_entries),
726        (
727            "chrom_array_addresses",
728            h.off_chrom_array_addresses,
729            h.len_chrom_array_addresses,
730        ),
731        ("spec_meta", h.off_spec_meta, h.len_spec_meta),
732        ("chrom_meta", h.off_chrom_meta, h.len_chrom_meta),
733        ("global_meta", h.off_global_meta, h.len_global_meta),
734        (
735            "container_spect",
736            h.off_spec_container,
737            h.len_spec_container,
738        ),
739        (
740            "container_chrom",
741            h.off_chrom_container,
742            h.len_chrom_container,
743        ),
744        ("spec_summary", h.off_spec_summary, h.len_spec_summary),
745        ("chrom_summary", h.off_chrom_summary, h.len_chrom_summary),
746        (
747            "spec_window_directory",
748            h.off_spec_window_directory,
749            h.len_spec_window_directory,
750        ),
751        (
752            "chrom_window_directory",
753            h.off_chrom_window_directory,
754            h.len_chrom_window_directory,
755        ),
756    ];
757
758    for &(name, off, len) in sections {
759        match off.checked_add(len) {
760            None => failures.push(format!("condition 7: {name} offset+length overflows u64")),
761            Some(end) if end > trailer_start => failures.push(format!(
762                "condition 7: {name} end ({end}) exceeds trailer_start ({trailer_start})"
763            )),
764            _ => {}
765        }
766    }
767
768    let mut sorted: Vec<(&str, u64, u64)> = sections
769        .iter()
770        .copied()
771        .filter(|&(_, _, len)| len > 0)
772        .collect();
773    sorted.sort_by_key(|&(_, off, _)| off);
774    for i in 1..sorted.len() {
775        let (prev_name, prev_off, prev_len) = sorted[i - 1];
776        let (curr_name, curr_off, _) = sorted[i];
777        match prev_off.checked_add(prev_len) {
778            None => failures.push(format!(
779                "condition 8: section {prev_name} offset+length overflows u64"
780            )),
781            Some(prev_end) if prev_end > curr_off => failures.push(format!(
782                "condition 8: sections {prev_name} and {curr_name} overlap \
783                 ({prev_name} ends at {prev_end}, {curr_name} starts at {curr_off})"
784            )),
785            _ => {}
786        }
787    }
788
789    for &(name, off, len) in sections {
790        if len > 0 && off % 8 != 0 {
791            failures.push(format!(
792                "condition 9: {name} offset ({off}) is not 8-byte aligned"
793            ));
794        }
795        if len > 0 && off < HEADER_SIZE as u64 {
796            failures.push(format!(
797                "condition 9: {name} offset ({off}) is inside the {HEADER_SIZE}-byte header"
798            ));
799        }
800    }
801
802    enforce_count_bounds(&mut failures, h);
803    enforce_section_element_counts(&mut failures, h);
804
805    failures
806}
807
808fn enforce_section_element_counts(failures: &mut Vec<String>, h: &Header) {
809    if h.compression_codec == CODEC_ZSTD {
810        return;
811    }
812    let checks: &[(&str, u64, u64, u64)] = &[
813        (
814            "spec_summary",
815            h.len_spec_summary,
816            h.spectrum_count,
817            SPEC_SUMMARY_SIZE as u64,
818        ),
819        (
820            "spec_entries",
821            h.len_spec_entries,
822            h.spectrum_count,
823            INDEX_ENTRY_BYTES as u64,
824        ),
825        (
826            "chrom_summary",
827            h.len_chrom_summary,
828            h.chrom_count,
829            CHROM_SUMMARY_SIZE as u64,
830        ),
831        (
832            "chrom_entries",
833            h.len_chrom_entries,
834            h.chrom_count,
835            INDEX_ENTRY_BYTES as u64,
836        ),
837    ];
838    for &(name, len, count, size) in checks {
839        match count.checked_mul(size) {
840            None => failures.push(format!("condition 14: {name} count × {size} overflows u64")),
841            Some(expected) if expected != len => failures.push(format!(
842                "condition 14: {name} length ({len}) != count ({count}) × {size}"
843            )),
844            _ => {}
845        }
846    }
847}
848
849fn enforce_count_bounds(failures: &mut Vec<String>, h: &Header) {
850    let checks: &[(&str, u64, u64)] = &[
851        ("spec_block_count", h.spec_block_count, h.total_file_size),
852        ("chrom_block_count", h.chrom_block_count, h.total_file_size),
853        ("spectrum_count", h.spectrum_count, h.total_file_size),
854        ("chrom_count", h.chrom_count, h.total_file_size),
855        (
856            "spec_meta_count",
857            h.spec_meta_count,
858            h.spec_meta_uncompressed_bytes,
859        ),
860        (
861            "spec_meta_numeric_count",
862            h.spec_meta_numeric_count,
863            h.spec_meta_uncompressed_bytes,
864        ),
865        (
866            "spec_meta_string_count",
867            h.spec_meta_string_count,
868            h.spec_meta_uncompressed_bytes,
869        ),
870        (
871            "chrom_meta_count",
872            h.chrom_meta_count,
873            h.chrom_meta_uncompressed_bytes,
874        ),
875        (
876            "chrom_meta_numeric_count",
877            h.chrom_meta_numeric_count,
878            h.chrom_meta_uncompressed_bytes,
879        ),
880        (
881            "chrom_meta_string_count",
882            h.chrom_meta_string_count,
883            h.chrom_meta_uncompressed_bytes,
884        ),
885        (
886            "spec_array_type_count",
887            h.spec_array_type_count,
888            h.total_file_size,
889        ),
890        (
891            "chrom_array_type_count",
892            h.chrom_array_type_count,
893            h.total_file_size,
894        ),
895    ];
896    for &(name, count, limit) in checks {
897        if count > limit {
898            failures.push(format!(
899                "condition 13: {name} ({count}) exceeds allowed bound ({limit})"
900            ));
901        }
902    }
903}
904
905#[inline]
906fn read_u32_at(bytes: &[u8], offset: usize) -> u32 {
907    u32::from_le_bytes(<[u8; 4]>::try_from(&bytes[offset..offset + 4]).unwrap())
908}
909
910#[inline]
911fn read_u64_at(bytes: &[u8], offset: usize) -> u64 {
912    u64::from_le_bytes(<[u8; 8]>::try_from(&bytes[offset..offset + 8]).unwrap())
913}
914
915#[inline]
916fn write_u8_at(buf: &mut [u8], offset: usize, value: u8) {
917    buf[offset] = value;
918}
919
920#[inline]
921fn write_u16_at(buf: &mut [u8], offset: usize, value: u16) {
922    buf[offset..offset + 2].copy_from_slice(&value.to_le_bytes());
923}
924
925#[inline]
926fn write_u32_at(buf: &mut [u8], offset: usize, value: u32) {
927    buf[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
928}
929
930#[inline]
931fn write_u64_at(buf: &mut [u8], offset: usize, value: u64) {
932    buf[offset..offset + 8].copy_from_slice(&value.to_le_bytes());
933}
934
935#[cfg(test)]
936mod tests {
937    use super::*;
938    use crate::ion::{
939        IonError,
940        format::{MAX_SUPPORTED_VERSION, MIN_SUPPORTED_VERSION},
941    };
942
943    fn valid_header_bytes() -> [u8; HEADER_SIZE] {
944        let mut h = [0u8; HEADER_SIZE];
945        h[0..8].copy_from_slice(&FILE_SIGNATURE);
946        h[HEADER_FORMAT_VERSION_OFFSET..HEADER_FORMAT_VERSION_OFFSET + 2]
947            .copy_from_slice(&CURRENT_VERSION.to_le_bytes());
948        h
949    }
950
951    #[test]
952    fn corrupt_reserved_area_is_rejected() {
953        let mut h = valid_header_bytes();
954        h[440] = 1;
955        assert!(Header::parse(&h).is_err());
956
957        let mut at_end = valid_header_bytes();
958        at_end[967] = 1;
959        assert!(Header::parse(&at_end).is_err());
960    }
961
962    fn header_bytes_with(build: impl FnOnce(&mut Header)) -> [u8; HEADER_SIZE] {
963        let mut header = Header {
964            format_version: CURRENT_VERSION,
965            ..Header::default()
966        };
967        build(&mut header);
968        let mut buf = [0u8; HEADER_SIZE];
969        header.write(&mut buf);
970        let crc = crc32fast::hash(&buf[0..HEADER_CRC32]);
971        buf[HEADER_CRC32..HEADER_SIZE].copy_from_slice(&crc.to_le_bytes());
972        buf
973    }
974
975    #[test]
976    fn reserved_block_must_be_zero() {
977        let base = header_bytes_with(|_| {});
978
979        for offset in [
980            RESERVED_BLOCK_START,
981            500,
982            700,
983            RESERVED_BLOCK_START + RESERVED_BLOCK_SIZE - 1,
984        ] {
985            let mut corrupted = base;
986            corrupted[offset] = 1;
987            let error = Header::parse(&corrupted).expect_err("nonzero reserved byte");
988            assert!(
989                error.to_string().contains("reserved block"),
990                "offset {offset}: unexpected error {error}"
991            );
992        }
993    }
994
995    #[test]
996    fn get_version_returns_none_on_short_buffer() {
997        let too_short = [0u8; HEADER_FORMAT_VERSION_OFFSET + 1];
998        assert_eq!(version_of(&too_short), None);
999    }
1000
1001    #[test]
1002    fn get_version_reads_little_endian_word() {
1003        let mut bytes = [0u8; HEADER_SIZE];
1004        bytes[HEADER_FORMAT_VERSION_OFFSET..HEADER_FORMAT_VERSION_OFFSET + 2]
1005            .copy_from_slice(&CURRENT_VERSION.to_le_bytes());
1006        assert_eq!(version_of(&bytes), Some(CURRENT_VERSION));
1007    }
1008
1009    #[test]
1010    fn get_version_handles_max_u16() {
1011        let mut bytes = [0u8; HEADER_SIZE];
1012        bytes[HEADER_FORMAT_VERSION_OFFSET..HEADER_FORMAT_VERSION_OFFSET + 2]
1013            .copy_from_slice(&u16::MAX.to_le_bytes());
1014        assert_eq!(version_of(&bytes), Some(u16::MAX));
1015    }
1016
1017    #[test]
1018    fn get_version_handles_exact_minimum_buffer_length() {
1019        let bytes = [0u8; HEADER_FORMAT_VERSION_OFFSET + 2];
1020        assert_eq!(version_of(&bytes), Some(0));
1021    }
1022
1023    #[test]
1024    fn header_offsets_match_clean_v1_layout() {
1025        assert_eq!(HEADER_FORMAT_VERSION_OFFSET, 9);
1026        assert_eq!(HEADER_CODEC_ID, 11);
1027        assert_eq!(HEADER_COMPRESSION_LEVEL, 12);
1028        assert_eq!(HEADER_ARRAY_FILTER_ID, 13);
1029        assert_eq!(HEADER_TARGET_BLOCK_SIZE, 16);
1030        assert_eq!(HEADER_TARGET_MZ_WINDOW, 24);
1031        assert_eq!(HEADER_OFFSET_SPEC_WINDOW_DIRECTORY, 32);
1032        assert_eq!(HEADER_LEN_SPEC_WINDOW_DIRECTORY, 40);
1033        assert_eq!(HEADER_OFFSET_SPEC_SUMMARY, 48);
1034        assert_eq!(HEADER_LEN_SPEC_SUMMARY, 56);
1035        assert_eq!(HEADER_OFFSET_SPEC_ENTRIES, 64);
1036        assert_eq!(HEADER_LEN_SPEC_ENTRIES, 72);
1037        assert_eq!(HEADER_OFFSET_SPEC_ARRAY_ADDRESSES, 80);
1038        assert_eq!(HEADER_LEN_SPEC_ARRAY_ADDRESSES, 88);
1039        assert_eq!(HEADER_OFFSET_CHROM_WINDOW_DIRECTORY, 96);
1040        assert_eq!(HEADER_LEN_CHROM_WINDOW_DIRECTORY, 104);
1041        assert_eq!(HEADER_OFFSET_CHROM_SUMMARY, 112);
1042        assert_eq!(HEADER_LEN_CHROM_SUMMARY, 120);
1043        assert_eq!(HEADER_OFFSET_CHROM_ENTRIES, 128);
1044        assert_eq!(HEADER_LEN_CHROM_ENTRIES, 136);
1045        assert_eq!(HEADER_OFFSET_CHROM_ARRAY_ADDRESSES, 144);
1046        assert_eq!(HEADER_LEN_CHROM_ARRAY_ADDRESSES, 152);
1047        assert_eq!(HEADER_OFFSET_SPEC_META, 160);
1048        assert_eq!(HEADER_LEN_SPEC_META, 168);
1049        assert_eq!(HEADER_OFFSET_CHROM_META, 176);
1050        assert_eq!(HEADER_LEN_CHROM_META, 184);
1051        assert_eq!(HEADER_OFFSET_GLOBAL_META, 192);
1052        assert_eq!(HEADER_LEN_GLOBAL_META, 200);
1053        assert_eq!(HEADER_OFFSET_PACKED_SPECTRA, 208);
1054        assert_eq!(HEADER_LEN_PACKED_SPECTRA, 216);
1055        assert_eq!(HEADER_OFFSET_PACKED_CHROMS, 224);
1056        assert_eq!(HEADER_LEN_PACKED_CHROMS, 232);
1057        assert_eq!(HEADER_SPECTRUM_BLOCK_COUNT, 240);
1058        assert_eq!(HEADER_CHROM_BLOCK_COUNT, 248);
1059        assert_eq!(HEADER_SPECTRUM_COUNT, 256);
1060        assert_eq!(HEADER_CHROM_COUNT, 264);
1061        assert_eq!(HEADER_SPEC_ARRAY_TYPE_COUNT, 272);
1062        assert_eq!(HEADER_CHROM_ARRAY_TYPE_COUNT, 280);
1063        assert_eq!(HEADER_SPEC_META_ROW_COUNT, 288);
1064        assert_eq!(HEADER_SPEC_META_NUMERIC_COUNT, 296);
1065        assert_eq!(HEADER_SPEC_META_STRING_COUNT, 304);
1066        assert_eq!(HEADER_CHROM_META_ROW_COUNT, 312);
1067        assert_eq!(HEADER_CHROM_META_NUMERIC_COUNT, 320);
1068        assert_eq!(HEADER_CHROM_META_STRING_COUNT, 328);
1069        assert_eq!(HEADER_GLOBAL_META_ROW_COUNT, 336);
1070        assert_eq!(HEADER_GLOBAL_META_NUMERIC_COUNT, 344);
1071        assert_eq!(HEADER_GLOBAL_META_STRING_COUNT, 352);
1072        assert_eq!(HEADER_SPEC_META_UNCOMPRESSED_SIZE, 360);
1073        assert_eq!(HEADER_CHROM_META_UNCOMPRESSED_SIZE, 368);
1074        assert_eq!(HEADER_GLOBAL_META_UNCOMPRESSED_SIZE, 376);
1075        assert_eq!(HEADER_PLAIN_LEN_SPEC_WINDOW_DIRECTORY, 384);
1076        assert_eq!(HEADER_PLAIN_LEN_CHROM_WINDOW_DIRECTORY, 392);
1077        assert_eq!(HEADER_TOTAL_FILE_SIZE, 400);
1078        assert_eq!(HEADER_META_GROUP_SIZE, 408);
1079        assert_eq!(HEADER_SPEC_META_GROUP_COUNT, 416);
1080        assert_eq!(HEADER_CHROM_META_GROUP_COUNT, 424);
1081        assert_eq!(RESERVED_BLOCK_START, 432);
1082        assert_eq!(RESERVED_BLOCK_SIZE, 536);
1083        assert_eq!(RESERVED_BLOCK_START + RESERVED_BLOCK_SIZE, 968);
1084        assert_eq!(HEADER_SPEC_WINDOW_DIRECTORY_CRC32, 968);
1085        assert_eq!(HEADER_SPEC_SUMMARY_CRC32, 972);
1086        assert_eq!(HEADER_SPEC_ENTRIES_CRC32, 976);
1087        assert_eq!(HEADER_SPEC_ARRAY_ADDRESSES_CRC32, 980);
1088        assert_eq!(HEADER_CHROM_WINDOW_DIRECTORY_CRC32, 984);
1089        assert_eq!(HEADER_CHROM_SUMMARY_CRC32, 988);
1090        assert_eq!(HEADER_CHROM_ENTRIES_CRC32, 992);
1091        assert_eq!(HEADER_CHROM_ARRAY_ADDRESSES_CRC32, 996);
1092        assert_eq!(HEADER_SPEC_DIRECTORY_CRC32, 1000);
1093        assert_eq!(HEADER_CHROM_DIRECTORY_CRC32, 1004);
1094        assert_eq!(HEADER_SPEC_META_CRC32, 1008);
1095        assert_eq!(HEADER_CHROM_META_CRC32, 1012);
1096        assert_eq!(HEADER_GLOBAL_META_CRC32, 1016);
1097        assert_eq!(HEADER_CRC32, 1020);
1098    }
1099
1100    #[test]
1101    fn write_then_parse_round_trips_every_field() {
1102        let mut original = Header {
1103            format_version: CURRENT_VERSION,
1104            compression_codec: 1,
1105            compression_level: 3,
1106            default_array_filter: 2,
1107            target_block_uncompressed_bytes: 0x0102_0304_0506_0708,
1108            off_spec_summary: 0x0010_0000_0000_0000,
1109            len_spec_summary: 0x0011_0000_0000_0001,
1110            off_chrom_summary: 0x0012_0000_0000_0002,
1111            len_chrom_summary: 0x0013_0000_0000_0003,
1112            off_spec_entries: 0x0014_0000_0000_0004,
1113            len_spec_entries: 0x0015_0000_0000_0005,
1114            off_spec_array_addresses: 0x0016_0000_0000_0006,
1115            len_spec_array_addresses: 0x0017_0000_0000_0007,
1116            off_chrom_entries: 0x0018_0000_0000_0008,
1117            len_chrom_entries: 0x0019_0000_0000_0009,
1118            off_chrom_array_addresses: 0x001a_0000_0000_000a,
1119            len_chrom_array_addresses: 0x001b_0000_0000_000b,
1120            off_spec_meta: 0x001c_0000_0000_000c,
1121            len_spec_meta: 0x001d_0000_0000_000d,
1122            off_chrom_meta: 0x001e_0000_0000_000e,
1123            len_chrom_meta: 0x001f_0000_0000_000f,
1124            off_global_meta: 0x0020_0000_0000_0010,
1125            len_global_meta: 0x0021_0000_0000_0011,
1126            off_spec_container: 0x0022_0000_0000_0012,
1127            len_spec_container: 0x0023_0000_0000_0013,
1128            off_chrom_container: 0x0024_0000_0000_0014,
1129            len_chrom_container: 0x0025_0000_0000_0015,
1130            spec_block_count: 0x0026_0000_0000_0016,
1131            chrom_block_count: 0x0027_0000_0000_0017,
1132            spectrum_count: 0x0028_0000_0000_0018,
1133            chrom_count: 0x0029_0000_0000_0019,
1134            spec_meta_count: 0x002a_0000_0000_001a,
1135            spec_meta_numeric_count: 0x002b_0000_0000_001b,
1136            spec_meta_string_count: 0x002c_0000_0000_001c,
1137            chrom_meta_count: 0x002d_0000_0000_001d,
1138            chrom_meta_numeric_count: 0x002e_0000_0000_001e,
1139            chrom_meta_string_count: 0x002f_0000_0000_001f,
1140            global_meta_count: 0x0030_0000_0000_0020,
1141            global_meta_numeric_count: 0x0031_0000_0000_0021,
1142            global_meta_string_count: 0x0032_0000_0000_0022,
1143            spec_array_type_count: 0x0033_0000_0000_0023,
1144            chrom_array_type_count: 0x0034_0000_0000_0024,
1145            spec_meta_uncompressed_bytes: 0x0035_0000_0000_0025,
1146            chrom_meta_uncompressed_bytes: 0x0036_0000_0000_0026,
1147            global_meta_uncompressed_bytes: 0x0037_0000_0000_0027,
1148            total_file_size: 0x0038_0000_0000_0028,
1149            meta_group_size: 0x0000_1234,
1150            spec_meta_group_count: 0x0039_0000_0000_0029,
1151            chrom_meta_group_count: 0x003a_0000_0000_002a,
1152            spec_summary_crc32: 0xAABB_CC0A,
1153            spec_entries_crc32: 0xAABB_CC0B,
1154            spec_array_addresses_crc32: 0xAABB_CC0C,
1155            chrom_summary_crc32: 0xAABB_CC0D,
1156            chrom_entries_crc32: 0xAABB_CC0E,
1157            chrom_array_addresses_crc32: 0xAABB_CC0F,
1158            target_mz_window: 0x0041_0031,
1159            spec_directory_crc32: 0xAABB_CC01,
1160            chrom_directory_crc32: 0xAABB_CC02,
1161            off_spec_window_directory: 0x003b_0000_0000_002b,
1162            len_spec_window_directory: 0x003c_0000_0000_002c,
1163            off_chrom_window_directory: 0x003d_0000_0000_002d,
1164            len_chrom_window_directory: 0x003e_0000_0000_002e,
1165            plain_len_spec_window_directory: 0x003f_0000_0000_002f,
1166            plain_len_chrom_window_directory: 0x0040_0000_0000_0030,
1167            spec_window_directory_crc32: 0xAABB_CC03,
1168            chrom_window_directory_crc32: 0xAABB_CC04,
1169            spec_meta_crc32: 0xAABB_CC05,
1170            chrom_meta_crc32: 0xAABB_CC06,
1171            global_meta_crc32: 0xAABB_CC07,
1172            header_crc32: 0xAABB_CC08,
1173        };
1174
1175        let mut buf = [0u8; HEADER_SIZE];
1176        original.write(&mut buf);
1177        let crc = crc32fast::hash(&buf[0..HEADER_CRC32]);
1178        buf[HEADER_CRC32..HEADER_SIZE].copy_from_slice(&crc.to_le_bytes());
1179        original.header_crc32 = crc;
1180
1181        let parsed = Header::parse(&buf).expect("round-trip parse failed");
1182
1183        assert_eq!(parsed.format_version, original.format_version);
1184        assert_eq!(parsed.compression_codec, original.compression_codec);
1185        assert_eq!(parsed.compression_level, original.compression_level);
1186        assert_eq!(parsed.default_array_filter, original.default_array_filter);
1187        assert_eq!(
1188            parsed.target_block_uncompressed_bytes,
1189            original.target_block_uncompressed_bytes
1190        );
1191        assert_eq!(parsed.off_spec_summary, original.off_spec_summary);
1192        assert_eq!(parsed.len_spec_summary, original.len_spec_summary);
1193        assert_eq!(parsed.off_chrom_summary, original.off_chrom_summary);
1194        assert_eq!(parsed.len_chrom_summary, original.len_chrom_summary);
1195        assert_eq!(parsed.off_spec_entries, original.off_spec_entries);
1196        assert_eq!(parsed.len_spec_entries, original.len_spec_entries);
1197        assert_eq!(
1198            parsed.off_spec_array_addresses,
1199            original.off_spec_array_addresses
1200        );
1201        assert_eq!(
1202            parsed.len_spec_array_addresses,
1203            original.len_spec_array_addresses
1204        );
1205        assert_eq!(parsed.off_chrom_entries, original.off_chrom_entries);
1206        assert_eq!(parsed.len_chrom_entries, original.len_chrom_entries);
1207        assert_eq!(
1208            parsed.off_chrom_array_addresses,
1209            original.off_chrom_array_addresses
1210        );
1211        assert_eq!(
1212            parsed.len_chrom_array_addresses,
1213            original.len_chrom_array_addresses
1214        );
1215        assert_eq!(parsed.off_spec_meta, original.off_spec_meta);
1216        assert_eq!(parsed.len_spec_meta, original.len_spec_meta);
1217        assert_eq!(parsed.off_chrom_meta, original.off_chrom_meta);
1218        assert_eq!(parsed.len_chrom_meta, original.len_chrom_meta);
1219        assert_eq!(parsed.off_global_meta, original.off_global_meta);
1220        assert_eq!(parsed.len_global_meta, original.len_global_meta);
1221        assert_eq!(parsed.off_spec_container, original.off_spec_container);
1222        assert_eq!(parsed.len_spec_container, original.len_spec_container);
1223        assert_eq!(parsed.off_chrom_container, original.off_chrom_container);
1224        assert_eq!(parsed.len_chrom_container, original.len_chrom_container);
1225        assert_eq!(parsed.spec_block_count, original.spec_block_count);
1226        assert_eq!(parsed.chrom_block_count, original.chrom_block_count);
1227        assert_eq!(parsed.spectrum_count, original.spectrum_count);
1228        assert_eq!(parsed.chrom_count, original.chrom_count);
1229        assert_eq!(parsed.spec_meta_count, original.spec_meta_count);
1230        assert_eq!(
1231            parsed.spec_meta_numeric_count,
1232            original.spec_meta_numeric_count
1233        );
1234        assert_eq!(
1235            parsed.spec_meta_string_count,
1236            original.spec_meta_string_count
1237        );
1238        assert_eq!(parsed.chrom_meta_count, original.chrom_meta_count);
1239        assert_eq!(
1240            parsed.chrom_meta_numeric_count,
1241            original.chrom_meta_numeric_count
1242        );
1243        assert_eq!(
1244            parsed.chrom_meta_string_count,
1245            original.chrom_meta_string_count
1246        );
1247        assert_eq!(parsed.global_meta_count, original.global_meta_count);
1248        assert_eq!(
1249            parsed.global_meta_numeric_count,
1250            original.global_meta_numeric_count
1251        );
1252        assert_eq!(
1253            parsed.global_meta_string_count,
1254            original.global_meta_string_count
1255        );
1256        assert_eq!(parsed.spec_array_type_count, original.spec_array_type_count);
1257        assert_eq!(
1258            parsed.chrom_array_type_count,
1259            original.chrom_array_type_count
1260        );
1261        assert_eq!(
1262            parsed.spec_meta_uncompressed_bytes,
1263            original.spec_meta_uncompressed_bytes
1264        );
1265        assert_eq!(
1266            parsed.chrom_meta_uncompressed_bytes,
1267            original.chrom_meta_uncompressed_bytes
1268        );
1269        assert_eq!(
1270            parsed.global_meta_uncompressed_bytes,
1271            original.global_meta_uncompressed_bytes
1272        );
1273        assert_eq!(parsed.total_file_size, original.total_file_size);
1274        assert_eq!(parsed.meta_group_size, original.meta_group_size);
1275        assert_eq!(parsed.spec_meta_group_count, original.spec_meta_group_count);
1276        assert_eq!(
1277            parsed.chrom_meta_group_count,
1278            original.chrom_meta_group_count
1279        );
1280        assert_eq!(parsed.spec_summary_crc32, original.spec_summary_crc32);
1281        assert_eq!(parsed.spec_entries_crc32, original.spec_entries_crc32);
1282        assert_eq!(
1283            parsed.spec_array_addresses_crc32,
1284            original.spec_array_addresses_crc32
1285        );
1286        assert_eq!(parsed.chrom_summary_crc32, original.chrom_summary_crc32);
1287        assert_eq!(parsed.chrom_entries_crc32, original.chrom_entries_crc32);
1288        assert_eq!(
1289            parsed.chrom_array_addresses_crc32,
1290            original.chrom_array_addresses_crc32
1291        );
1292        assert_eq!(parsed.target_mz_window, original.target_mz_window);
1293        assert_eq!(parsed.spec_directory_crc32, original.spec_directory_crc32);
1294        assert_eq!(parsed.chrom_directory_crc32, original.chrom_directory_crc32);
1295        assert_eq!(
1296            parsed.off_spec_window_directory,
1297            original.off_spec_window_directory
1298        );
1299        assert_eq!(
1300            parsed.len_spec_window_directory,
1301            original.len_spec_window_directory
1302        );
1303        assert_eq!(
1304            parsed.off_chrom_window_directory,
1305            original.off_chrom_window_directory
1306        );
1307        assert_eq!(
1308            parsed.len_chrom_window_directory,
1309            original.len_chrom_window_directory
1310        );
1311        assert_eq!(
1312            parsed.plain_len_spec_window_directory,
1313            original.plain_len_spec_window_directory
1314        );
1315        assert_eq!(
1316            parsed.plain_len_chrom_window_directory,
1317            original.plain_len_chrom_window_directory
1318        );
1319        assert_eq!(
1320            parsed.spec_window_directory_crc32,
1321            original.spec_window_directory_crc32
1322        );
1323        assert_eq!(
1324            parsed.chrom_window_directory_crc32,
1325            original.chrom_window_directory_crc32
1326        );
1327        assert_eq!(parsed.spec_meta_crc32, original.spec_meta_crc32);
1328        assert_eq!(parsed.chrom_meta_crc32, original.chrom_meta_crc32);
1329        assert_eq!(parsed.global_meta_crc32, original.global_meta_crc32);
1330        assert_eq!(parsed.header_crc32, original.header_crc32);
1331    }
1332
1333    #[test]
1334    fn check_section_layout_accepts_empty_window_directories() {
1335        let header = Header {
1336            total_file_size: 4096,
1337            ..Default::default()
1338        };
1339
1340        let failures = check_section_layout(&header);
1341
1342        assert!(
1343            failures
1344                .iter()
1345                .all(|f| !f.contains("spec_window_directory")
1346                    && !f.contains("chrom_window_directory")),
1347            "empty window directories must not fail layout checks: {failures:?}"
1348        );
1349    }
1350
1351    #[test]
1352    fn check_section_layout_rejects_spec_window_directory_inside_header() {
1353        let header = Header {
1354            total_file_size: 4096,
1355            off_spec_window_directory: 16,
1356            len_spec_window_directory: 32,
1357            ..Default::default()
1358        };
1359
1360        let failures = check_section_layout(&header);
1361
1362        assert!(
1363            failures.iter().any(|f| f.contains("spec_window_directory")),
1364            "expected a spec_window_directory layout failure, got: {failures:?}"
1365        );
1366    }
1367
1368    #[test]
1369    fn check_section_layout_rejects_chrom_window_directory_overlap() {
1370        let header = Header {
1371            total_file_size: 4096,
1372            off_global_meta: 1024,
1373            len_global_meta: 64,
1374            off_chrom_window_directory: 1040,
1375            len_chrom_window_directory: 32,
1376            ..Default::default()
1377        };
1378
1379        let failures = check_section_layout(&header);
1380
1381        assert!(
1382            failures
1383                .iter()
1384                .any(|f| f.contains("chrom_window_directory")),
1385            "expected a chrom_window_directory overlap failure, got: {failures:?}"
1386        );
1387    }
1388
1389    #[test]
1390    fn condition_13_bounds_meta_by_uncompressed_size_1() {
1391        let mut header = Header {
1392            total_file_size: 100,
1393            spec_meta_uncompressed_bytes: 100_000,
1394            spec_meta_count: 50_000,
1395            ..Header::default()
1396        };
1397
1398        let mut failures = Vec::new();
1399        enforce_count_bounds(&mut failures, &header);
1400        assert!(
1401            failures.iter().all(|f| !f.contains("spec_meta_count")),
1402            "spec_meta_count under the uncompressed-size limit must not fail: {failures:?}"
1403        );
1404
1405        header.spec_meta_count = 200_000;
1406        let mut failures = Vec::new();
1407        enforce_count_bounds(&mut failures, &header);
1408        assert!(
1409            failures.iter().any(|f| f.contains("spec_meta_count")),
1410            "spec_meta_count over the uncompressed-size limit must fail: {failures:?}"
1411        );
1412    }
1413
1414    fn header_bytes_at_version(version: u16) -> [u8; HEADER_SIZE] {
1415        let mut buf = header_bytes_with(|_| {});
1416        write_u16_at(&mut buf, HEADER_FORMAT_VERSION_OFFSET, version);
1417        let crc = crc32fast::hash(&buf[0..HEADER_CRC32]);
1418        write_u32_at(&mut buf, HEADER_CRC32, crc);
1419        buf
1420    }
1421
1422    #[test]
1423    fn update_rewrites_older_supported_version_to_current() {
1424        let mut buf = header_bytes_at_version(MIN_SUPPORTED_VERSION);
1425        assert_eq!(set_version(&mut buf), Ok(true));
1426        assert_eq!(version_of(&buf), Some(CURRENT_VERSION));
1427        assert_eq!(
1428            read_u32_at(&buf, HEADER_CRC32),
1429            crc32fast::hash(&buf[0..HEADER_CRC32])
1430        );
1431        assert!(Header::parse(&buf).is_ok());
1432    }
1433
1434    #[test]
1435    fn update_leaves_current_version_untouched() {
1436        let mut buf = header_bytes_at_version(CURRENT_VERSION);
1437        let before = buf;
1438        assert_eq!(set_version(&mut buf), Ok(false));
1439        assert_eq!(buf, before);
1440    }
1441
1442    #[test]
1443    fn update_rejects_unsupported_version() {
1444        let mut buf = header_bytes_at_version(MAX_SUPPORTED_VERSION + 1);
1445        let before = buf;
1446        assert_eq!(
1447            set_version(&mut buf),
1448            Err(IonError::UnsupportedFormatVersion(
1449                MAX_SUPPORTED_VERSION + 1
1450            ))
1451        );
1452        assert_eq!(buf, before);
1453    }
1454
1455    #[test]
1456    fn update_rejects_corrupt_header_crc() {
1457        let mut buf = header_bytes_at_version(MIN_SUPPORTED_VERSION);
1458        buf[HEADER_CRC32] ^= 0xff;
1459        let before = buf;
1460        let error = set_version(&mut buf).unwrap_err();
1461        assert!(error.contains("header_crc32 mismatch"), "{error}");
1462        assert_eq!(buf, before);
1463    }
1464
1465    #[test]
1466    fn update_rejects_bad_signature_and_short_buffer() {
1467        let mut buf = header_bytes_at_version(MIN_SUPPORTED_VERSION);
1468        buf[0] = b'X';
1469        assert!(set_version(&mut buf).is_err());
1470
1471        let mut short = [0u8; HEADER_SIZE - 1];
1472        assert!(set_version(&mut short).is_err());
1473    }
1474}