idb/innodb/
page.rs

1//! InnoDB page header and trailer parsing.
2//!
3//! Every InnoDB page begins with a 38-byte FIL header ([`FilHeader`]) containing
4//! the checksum, page number, prev/next pointers, LSN, page type, flush LSN, and
5//! space ID. The last 8 bytes form the FIL trailer ([`FilTrailer`]) with the
6//! old-style checksum and low 32 bits of the LSN.
7//!
8//! Page 0 of every tablespace also contains the FSP header ([`FspHeader`]) at
9//! byte offset 38, which stores the space ID, tablespace size, and feature flags
10//! (page size, compression, encryption).
11
12use byteorder::{BigEndian, ByteOrder};
13use serde::Serialize;
14
15use crate::innodb::constants::*;
16use crate::innodb::page_types::PageType;
17
18/// Parsed FIL header (38 bytes, present at the start of every InnoDB page).
19#[derive(Debug, Clone, Serialize)]
20pub struct FilHeader {
21    /// Checksum (or space id in older formats). Bytes 0-3.
22    pub checksum: u32,
23    /// Page number within the tablespace. Bytes 4-7.
24    pub page_number: u32,
25    /// Previous page in the doubly-linked list. Bytes 8-11.
26    /// FIL_NULL (0xFFFFFFFF) if not used.
27    pub prev_page: u32,
28    /// Next page in the doubly-linked list. Bytes 12-15.
29    /// FIL_NULL (0xFFFFFFFF) if not used.
30    pub next_page: u32,
31    /// LSN of newest modification to this page. Bytes 16-23.
32    pub lsn: u64,
33    /// Page type. Bytes 24-25.
34    pub page_type: PageType,
35    /// Flush LSN (only meaningful for page 0 of system tablespace). Bytes 26-33.
36    pub flush_lsn: u64,
37    /// Space ID this page belongs to. Bytes 34-37.
38    pub space_id: u32,
39}
40
41impl FilHeader {
42    /// Parse a FIL header from a byte slice.
43    ///
44    /// The slice must be at least SIZE_FIL_HEAD (38) bytes.
45    pub fn parse(data: &[u8]) -> Option<Self> {
46        if data.len() < SIZE_FIL_HEAD {
47            return None;
48        }
49
50        Some(FilHeader {
51            checksum: BigEndian::read_u32(&data[FIL_PAGE_SPACE_OR_CHKSUM..]),
52            page_number: BigEndian::read_u32(&data[FIL_PAGE_OFFSET..]),
53            prev_page: BigEndian::read_u32(&data[FIL_PAGE_PREV..]),
54            next_page: BigEndian::read_u32(&data[FIL_PAGE_NEXT..]),
55            lsn: BigEndian::read_u64(&data[FIL_PAGE_LSN..]),
56            page_type: PageType::from_u16(BigEndian::read_u16(&data[FIL_PAGE_TYPE..])),
57            flush_lsn: BigEndian::read_u64(&data[FIL_PAGE_FILE_FLUSH_LSN..]),
58            space_id: BigEndian::read_u32(&data[FIL_PAGE_SPACE_ID..]),
59        })
60    }
61
62    /// Returns true if prev_page is FIL_NULL (not used).
63    pub fn has_prev(&self) -> bool {
64        self.prev_page != FIL_NULL && self.prev_page != 0
65    }
66
67    /// Returns true if next_page is FIL_NULL (not used).
68    pub fn has_next(&self) -> bool {
69        self.next_page != FIL_NULL && self.next_page != 0
70    }
71}
72
73/// Parsed FIL trailer (8 bytes, present at the end of every InnoDB page).
74#[derive(Debug, Clone, Serialize)]
75pub struct FilTrailer {
76    /// Old-style checksum (or low 32 bits of LSN, depending on version). Bytes 0-3 of trailer.
77    pub checksum: u32,
78    /// Low 32 bits of the LSN. Bytes 4-7 of trailer.
79    pub lsn_low32: u32,
80}
81
82impl FilTrailer {
83    /// Parse a FIL trailer from a byte slice.
84    ///
85    /// The slice should be the last 8 bytes of the page, or at least 8 bytes
86    /// starting from the trailer position.
87    pub fn parse(data: &[u8]) -> Option<Self> {
88        if data.len() < SIZE_FIL_TRAILER {
89            return None;
90        }
91
92        Some(FilTrailer {
93            checksum: BigEndian::read_u32(&data[0..]),
94            lsn_low32: BigEndian::read_u32(&data[4..]),
95        })
96    }
97}
98
99/// Parsed FSP header (from page 0 of a tablespace, starts at FIL_PAGE_DATA).
100#[derive(Debug, Clone, Serialize)]
101pub struct FspHeader {
102    /// Space ID.
103    pub space_id: u32,
104    /// Size of the tablespace in pages.
105    pub size: u32,
106    /// Minimum page number not yet initialized.
107    pub free_limit: u32,
108    /// Space flags (contains page size, compression, encryption info).
109    pub flags: u32,
110    /// Number of used pages in the FSP_FREE_FRAG list.
111    pub frag_n_used: u32,
112}
113
114impl FspHeader {
115    /// Parse the FSP header from page 0's data area.
116    ///
117    /// `data` should be the full page buffer. FSP header starts at FIL_PAGE_DATA (byte 38).
118    pub fn parse(page_data: &[u8]) -> Option<Self> {
119        let offset = FIL_PAGE_DATA;
120        if page_data.len() < offset + FSP_HEADER_SIZE {
121            return None;
122        }
123        let data = &page_data[offset..];
124
125        Some(FspHeader {
126            space_id: BigEndian::read_u32(&data[FSP_SPACE_ID..]),
127            size: BigEndian::read_u32(&data[FSP_SIZE..]),
128            free_limit: BigEndian::read_u32(&data[FSP_FREE_LIMIT..]),
129            flags: BigEndian::read_u32(&data[FSP_SPACE_FLAGS..]),
130            frag_n_used: BigEndian::read_u32(&data[FSP_FRAG_N_USED..]),
131        })
132    }
133
134    /// Extract the page size from FSP flags.
135    ///
136    /// Returns the page size in bytes. For MariaDB full_crc32 tablespaces,
137    /// the page size is in bits 0-3 instead of bits 6-9.
138    pub fn page_size_from_flags(&self) -> u32 {
139        use crate::innodb::vendor::detect_vendor_from_flags;
140
141        let vendor_info = detect_vendor_from_flags(self.flags);
142        self.page_size_from_flags_with_vendor(&vendor_info)
143    }
144
145    /// Extract the page size from FSP flags with explicit vendor info.
146    pub fn page_size_from_flags_with_vendor(
147        &self,
148        vendor_info: &crate::innodb::vendor::VendorInfo,
149    ) -> u32 {
150        let ssize = if vendor_info.is_full_crc32() {
151            // MariaDB full_crc32: page size in bits 0-3
152            self.flags & MARIADB_FSP_FLAGS_FCRC32_PAGE_SSIZE_MASK
153        } else {
154            // MySQL / MariaDB original: page size in bits 6-9
155            (self.flags & FSP_FLAGS_MASK_PAGE_SSIZE) >> FSP_FLAGS_POS_PAGE_SSIZE
156        };
157
158        if ssize == 0 {
159            // Default/uncompressed: 16K
160            SIZE_PAGE_DEFAULT
161        } else {
162            // ssize encodes page size as: 1 << (ssize + 9)
163            // ssize=3 => 4K, ssize=4 => 8K, ssize=5 => 16K, ssize=6 => 32K, ssize=7 => 64K
164            1u32 << (ssize + 9)
165        }
166    }
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172
173    fn make_fil_header_bytes(
174        checksum: u32,
175        page_num: u32,
176        prev: u32,
177        next: u32,
178        lsn: u64,
179        page_type: u16,
180        flush_lsn: u64,
181        space_id: u32,
182    ) -> Vec<u8> {
183        let mut buf = vec![0u8; SIZE_FIL_HEAD];
184        BigEndian::write_u32(&mut buf[FIL_PAGE_SPACE_OR_CHKSUM..], checksum);
185        BigEndian::write_u32(&mut buf[FIL_PAGE_OFFSET..], page_num);
186        BigEndian::write_u32(&mut buf[FIL_PAGE_PREV..], prev);
187        BigEndian::write_u32(&mut buf[FIL_PAGE_NEXT..], next);
188        BigEndian::write_u64(&mut buf[FIL_PAGE_LSN..], lsn);
189        BigEndian::write_u16(&mut buf[FIL_PAGE_TYPE..], page_type);
190        BigEndian::write_u64(&mut buf[FIL_PAGE_FILE_FLUSH_LSN..], flush_lsn);
191        BigEndian::write_u32(&mut buf[FIL_PAGE_SPACE_ID..], space_id);
192        buf
193    }
194
195    #[test]
196    fn test_fil_header_parse() {
197        let data = make_fil_header_bytes(
198            0x12345678, // checksum
199            42,         // page number
200            41,         // prev page
201            43,         // next page
202            1000,       // lsn
203            17855,      // INDEX page type
204            2000,       // flush lsn
205            5,          // space id
206        );
207        let hdr = FilHeader::parse(&data).unwrap();
208        assert_eq!(hdr.checksum, 0x12345678);
209        assert_eq!(hdr.page_number, 42);
210        assert_eq!(hdr.prev_page, 41);
211        assert_eq!(hdr.next_page, 43);
212        assert_eq!(hdr.lsn, 1000);
213        assert_eq!(hdr.page_type, PageType::Index);
214        assert_eq!(hdr.flush_lsn, 2000);
215        assert_eq!(hdr.space_id, 5);
216        assert!(hdr.has_prev());
217        assert!(hdr.has_next());
218    }
219
220    #[test]
221    fn test_fil_header_null_pages() {
222        let data = make_fil_header_bytes(0, 0, FIL_NULL, FIL_NULL, 0, 0, 0, 0);
223        let hdr = FilHeader::parse(&data).unwrap();
224        assert!(!hdr.has_prev());
225        assert!(!hdr.has_next());
226    }
227
228    #[test]
229    fn test_fil_header_too_short() {
230        let data = vec![0u8; 10];
231        assert!(FilHeader::parse(&data).is_none());
232    }
233
234    #[test]
235    fn test_fil_trailer_parse() {
236        let mut data = vec![0u8; 8];
237        BigEndian::write_u32(&mut data[0..], 0xAABBCCDD);
238        BigEndian::write_u32(&mut data[4..], 0x11223344);
239        let trl = FilTrailer::parse(&data).unwrap();
240        assert_eq!(trl.checksum, 0xAABBCCDD);
241        assert_eq!(trl.lsn_low32, 0x11223344);
242    }
243
244    #[test]
245    fn test_fsp_header_page_size() {
246        let fsp = FspHeader {
247            space_id: 0,
248            size: 100,
249            free_limit: 64,
250            flags: 0, // ssize=0 => default 16K
251            frag_n_used: 0,
252        };
253        assert_eq!(fsp.page_size_from_flags(), SIZE_PAGE_DEFAULT);
254
255        // ssize=5 => 16384
256        let fsp_16k = FspHeader {
257            flags: 5 << FSP_FLAGS_POS_PAGE_SSIZE,
258            ..fsp
259        };
260        assert_eq!(fsp_16k.page_size_from_flags(), 16384);
261
262        // ssize=3 => 4096
263        let fsp_4k = FspHeader {
264            flags: 3 << FSP_FLAGS_POS_PAGE_SSIZE,
265            ..fsp
266        };
267        assert_eq!(fsp_4k.page_size_from_flags(), 4096);
268    }
269
270    #[test]
271    fn test_fsp_header_page_size_mariadb_full_crc32() {
272        use crate::innodb::vendor::{MariaDbFormat, VendorInfo};
273
274        let vendor = VendorInfo::mariadb(MariaDbFormat::FullCrc32);
275
276        // MariaDB full_crc32: ssize in bits 0-3, marker at bit 4
277        // ssize=5 (16K) + full_crc32 marker
278        let fsp = FspHeader {
279            space_id: 0,
280            size: 100,
281            free_limit: 64,
282            flags: 0x10 | 5, // bit 4 marker + ssize=5 in bits 0-3
283            frag_n_used: 0,
284        };
285        assert_eq!(fsp.page_size_from_flags_with_vendor(&vendor), 16384);
286
287        // ssize=3 (4K)
288        let fsp_4k = FspHeader {
289            flags: 0x10 | 3,
290            ..fsp
291        };
292        assert_eq!(fsp_4k.page_size_from_flags_with_vendor(&vendor), 4096);
293
294        // ssize=0 (default 16K)
295        let fsp_default = FspHeader {
296            flags: 0x10,
297            ..fsp
298        };
299        assert_eq!(
300            fsp_default.page_size_from_flags_with_vendor(&vendor),
301            SIZE_PAGE_DEFAULT
302        );
303    }
304}
idb/innodb/page.rs

idb/innodb/
page.rs
