Skip to main content

json_slabs/
read.rs

1//! [`ParsedFile`] and [`SlabDirectory`], and other reading-related types.
2
3use std::io::{self, Read};
4
5use crate::{
6    FIXED_HEADER_SIZE, Header, MAGIC, SLAB_TABLE_ENTRY_SIZE, SlabBytes, SlabPlaceholder,
7    SlabPrimitive, SlabTableEntry, SlabType, VERSION,
8};
9use thiserror::Error;
10
11/// Error reading the fixed header, slab table, or slab data extents.
12/// Returned by [`Header::parse`], [`SlabTableEntry::parse`], and
13/// [`ParsedFile::parse`].
14#[derive(Debug, Error)]
15pub enum ParseError {
16    /// Buffer is shorter than the 20-byte fixed header. Payload is the
17    /// actual buffer length.
18    #[error("file too short: need {FIXED_HEADER_SIZE} bytes, got {0}")]
19    TooShort(usize),
20    /// The first 8 bytes do not match [`MAGIC`].
21    #[error("bad magic bytes")]
22    BadMagic,
23    /// The `version` field is not [`VERSION`].
24    #[error("unsupported version {0}")]
25    UnsupportedVersion(u32),
26    /// The header's `slab_count` is zero. A well-formed file always has
27    /// at least the root JSON slab.
28    #[error("file has no slabs")]
29    NoSlabs,
30    /// The slab table extends past the end of the input buffer.
31    #[error("slab table overruns buffer")]
32    SlabTableOverrun,
33    /// The header's `root_json_slab_index` is not less than its `slab_count`.
34    #[error("root slab index {index} out of range (slab count: {slab_count})")]
35    RootIndexOutOfRange {
36        /// The out-of-range root slab index.
37        index: usize,
38        /// The file's total slab count.
39        slab_count: usize,
40    },
41    /// A slab-table entry's type byte does not decode to a known
42    /// [`SlabType`].
43    #[error("slab {index} has unknown type {type_byte:#x}")]
44    UnknownSlabType {
45        /// Slab table index of the offending entry.
46        index: usize,
47        /// The raw type byte that failed to decode.
48        type_byte: u32,
49    },
50    /// A slab's byte length is not a multiple of its element size.
51    #[error("slab {index} byte length {byte_length} not a multiple of element size {element_size}")]
52    UnalignedSlabLength {
53        /// Slab table index of the offending entry.
54        index: usize,
55        /// The reported byte length.
56        byte_length: u32,
57        /// The element size implied by the slab's type.
58        element_size: usize,
59    },
60    /// A slab's `[start_offset, start_offset + byte_length)` range does not
61    /// fit inside the input buffer.
62    #[error("slab {index} data overruns buffer")]
63    SlabDataOverrun {
64        /// Slab table index of the offending entry.
65        index: usize,
66    },
67    /// The slab designated by `root_json_slab_index` is not of type
68    /// [`SlabType::Json`].
69    #[error("root slab is not TYPE_JSON")]
70    RootNotJson,
71}
72
73impl Header {
74    /// Parse the 20-byte fixed header. Validates magic, version,
75    /// `slab_count > 0`, and `root_json_slab_index < slab_count`. Does not
76    /// look at the slab table.
77    pub fn parse(bytes: &[u8]) -> Result<Self, ParseError> {
78        if bytes.len() < FIXED_HEADER_SIZE {
79            return Err(ParseError::TooShort(bytes.len()));
80        }
81        if bytes[0..8] != MAGIC {
82            return Err(ParseError::BadMagic);
83        }
84        let version = u32::from_le_bytes(bytes[8..12].try_into().unwrap());
85        if version != VERSION {
86            return Err(ParseError::UnsupportedVersion(version));
87        }
88        let slab_count = u32::from_le_bytes(bytes[12..16].try_into().unwrap()) as usize;
89        let root_json_slab_index = u32::from_le_bytes(bytes[16..20].try_into().unwrap()) as usize;
90
91        if slab_count == 0 {
92            return Err(ParseError::NoSlabs);
93        }
94        if root_json_slab_index >= slab_count {
95            return Err(ParseError::RootIndexOutOfRange {
96                index: root_json_slab_index,
97                slab_count,
98            });
99        }
100
101        Ok(Header {
102            slab_count,
103            root_json_slab_index,
104        })
105    }
106}
107
108impl SlabTableEntry {
109    /// Parse one 12-byte slab-table entry. Validates the type byte and
110    /// that `byte_length` is a multiple of the element size. Does not
111    /// validate that the slab fits in any particular buffer — the caller
112    /// supplies that bound.
113    ///
114    /// `bytes` must be at least `SLAB_TABLE_ENTRY_SIZE` long; only the
115    /// first 12 bytes are read.
116    pub fn parse(bytes: &[u8], index: usize) -> Result<Self, ParseError> {
117        let type_byte = u32::from_le_bytes(bytes[0..4].try_into().unwrap());
118        let start_offset = u32::from_le_bytes(bytes[4..8].try_into().unwrap()) as u64;
119        let byte_length = u32::from_le_bytes(bytes[8..12].try_into().unwrap()) as u64;
120
121        let slab_type = SlabType::try_from(type_byte)
122            .map_err(|type_byte| ParseError::UnknownSlabType { index, type_byte })?;
123
124        let element_size = slab_type.element_size() as u64;
125        if !byte_length.is_multiple_of(element_size) {
126            return Err(ParseError::UnalignedSlabLength {
127                index,
128                byte_length: byte_length as u32,
129                element_size: element_size as usize,
130            });
131        }
132
133        Ok(SlabTableEntry {
134            slab_type,
135            start_offset,
136            byte_length,
137        })
138    }
139}
140
141/// Low-level alternative to [`ParsedFile`]. A `SlabDirectory` consumes the entire
142/// front-part of the file, including the header.
143#[derive(Debug, Clone)]
144pub struct SlabDirectory {
145    /// Decoded 20-byte fixed header.
146    pub header: Header,
147    /// One entry per slab, in slab-table order.
148    pub entries: Vec<SlabTableEntry>,
149}
150
151impl SlabDirectory {
152    /// Parse the fixed header and slab table from the front of an
153    /// in-memory buffer. Payload bytes are not read or validated; call
154    /// [`SlabDirectory::validate_extents`] separately to check that
155    /// every slab body fits.
156    pub fn parse(bytes: &[u8]) -> Result<Self, ParseError> {
157        let header = Header::parse(bytes)?;
158
159        let table_end = FIXED_HEADER_SIZE + header.slab_count * SLAB_TABLE_ENTRY_SIZE;
160        if table_end > bytes.len() {
161            return Err(ParseError::SlabTableOverrun);
162        }
163
164        let mut entries = Vec::with_capacity(header.slab_count);
165        for i in 0..header.slab_count {
166            let pos = FIXED_HEADER_SIZE + i * SLAB_TABLE_ENTRY_SIZE;
167            entries.push(SlabTableEntry::parse(
168                &bytes[pos..pos + SLAB_TABLE_ENTRY_SIZE],
169                i,
170            )?);
171        }
172
173        Ok(Self { header, entries })
174    }
175
176    /// Read the fixed header and slab table from a stream. Advances
177    /// `r` by exactly `FIXED_HEADER_SIZE + slab_count *
178    /// SLAB_TABLE_ENTRY_SIZE` bytes on success. Payload bytes are not
179    /// touched — the reader is left positioned at the first byte after
180    /// the slab table.
181    ///
182    /// Header/table decode errors are surfaced as
183    /// [`io::ErrorKind::InvalidData`].
184    pub fn read<R: Read>(r: &mut R) -> io::Result<Self> {
185        let mut header_buf = [0u8; FIXED_HEADER_SIZE];
186        r.read_exact(&mut header_buf)?;
187        let header = Header::parse(&header_buf)
188            .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
189
190        let table_len = header
191            .slab_count
192            .checked_mul(SLAB_TABLE_ENTRY_SIZE)
193            .ok_or_else(|| {
194                io::Error::new(io::ErrorKind::InvalidData, "slab table size overflow")
195            })?;
196        let mut table = vec![0u8; table_len];
197        r.read_exact(&mut table)?;
198
199        let mut entries = Vec::with_capacity(header.slab_count);
200        for i in 0..header.slab_count {
201            let pos = i * SLAB_TABLE_ENTRY_SIZE;
202            let entry = SlabTableEntry::parse(&table[pos..pos + SLAB_TABLE_ENTRY_SIZE], i)
203                .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
204            entries.push(entry);
205        }
206
207        Ok(Self { header, entries })
208    }
209
210    /// Check that every slab's `[start_offset, start_offset +
211    /// byte_length)` range fits within a container of `file_len` bytes.
212    pub fn validate_extents(&self, file_len: u64) -> Result<(), ParseError> {
213        for (index, entry) in self.entries.iter().enumerate() {
214            entry
215                .start_offset
216                .checked_add(entry.byte_length)
217                .filter(|&e| e <= file_len)
218                .ok_or(ParseError::SlabDataOverrun { index })?;
219        }
220        Ok(())
221    }
222
223    /// Index of the slab that holds the root JSON skeleton.
224    pub fn root_json_index(&self) -> usize {
225        self.header.root_json_slab_index
226    }
227
228    /// Slab-table entry for the root JSON skeleton slab.
229    pub fn root_entry(&self) -> &SlabTableEntry {
230        &self.entries[self.root_json_index()]
231    }
232
233    /// Total byte size of the header + slab table (i.e. the byte offset
234    /// at which slab payloads may start).
235    pub fn header_and_table_size(&self) -> u64 {
236        (FIXED_HEADER_SIZE + self.entries.len() * SLAB_TABLE_ENTRY_SIZE) as u64
237    }
238}
239
240/// The JSLB file contents, parsed from a slice of bytes.
241///
242/// Use [`SlabDirectory`] for a lower-level reading API, or if you don't
243/// want to materialize the entire file contents into memory.
244#[derive(Debug)]
245pub struct ParsedFile<'a> {
246    root_json_slab_index: usize,
247    slabs: Vec<SlabBytes<'a>>,
248}
249
250impl<'a> ParsedFile<'a> {
251    /// Parse a `.jslb` byte buffer. Validates the fixed header, the slab
252    /// table, that each slab's bytes fit in `data`, and that the root
253    /// slab has type [`SlabType::Json`]. Returns borrowed views into
254    /// `data`.
255    pub fn parse(data: &'a [u8]) -> Result<ParsedFile<'a>, ParseError> {
256        let dir = SlabDirectory::parse(data)?;
257        dir.validate_extents(data.len() as u64)?;
258
259        let slabs = dir
260            .entries
261            .iter()
262            .map(|entry| SlabBytes {
263                slab_type: entry.slab_type,
264                bytes: &data[entry.start_offset as usize
265                    ..(entry.start_offset + entry.byte_length) as usize],
266            })
267            .collect::<Vec<_>>();
268
269        let root_json_slab_index = dir.header.root_json_slab_index;
270        if slabs[root_json_slab_index].slab_type != SlabType::Json {
271            return Err(ParseError::RootNotJson);
272        }
273
274        Ok(ParsedFile {
275            root_json_slab_index,
276            slabs,
277        })
278    }
279
280    /// All slabs in declaration order.
281    pub fn slabs(&self) -> &[SlabBytes<'a>] {
282        &self.slabs
283    }
284
285    /// Index of the slab that holds the root JSON skeleton.
286    pub fn root_json_slab_index(&self) -> usize {
287        self.root_json_slab_index
288    }
289
290    /// Raw bytes of the root JSON skeleton slab.
291    pub fn root_json_bytes(&self) -> &'a [u8] {
292        self.slabs[self.root_json_slab_index].bytes
293    }
294
295    /// Look up a placeholder's slab. Returns the underlying [`SlabBytes`]
296    /// for callers that want to handle decoding themselves.
297    pub fn slab_at(&self, p: SlabPlaceholder) -> Result<&SlabBytes<'a>, DecodeError> {
298        self.slabs.get(p.0).ok_or(DecodeError::SlabIndexOutOfRange {
299            index: p.0,
300            slab_count: self.slabs.len(),
301        })
302    }
303
304    /// Read a typed-array slab as `Vec<T>`. The slab's stored on-disk
305    /// type must match `T`'s on-disk type.
306    pub fn read<T: SlabPrimitive>(&self, p: SlabPlaceholder) -> Result<Vec<T>, DecodeError> {
307        let slab = self.slab_at(p)?;
308        let expected = T::SLAB_TYPE;
309        if slab.slab_type != expected {
310            return Err(DecodeError::SlabTypeMismatch {
311                index: p.0,
312                expected,
313                found: slab.slab_type,
314            });
315        }
316        let elem_size = expected.element_size();
317        Ok(slab
318            .bytes
319            .chunks_exact(elem_size)
320            .map(T::from_le_bytes)
321            .collect())
322    }
323
324    /// Read a TYPE_JSON sub-slab as raw bytes. The slab must have type
325    /// [`SlabType::Json`]. Use this when you want to decode the JSON
326    /// yourself instead of going through `serde_json::from_slice`.
327    pub fn read_subjson_bytes(&self, p: SlabPlaceholder) -> Result<&'a [u8], DecodeError> {
328        let slab = self.slab_at(p)?;
329        if slab.slab_type != SlabType::Json {
330            return Err(DecodeError::SlabTypeMismatch {
331                index: p.0,
332                expected: SlabType::Json,
333                found: slab.slab_type,
334            });
335        }
336        Ok(slab.bytes)
337    }
338
339    /// Raw bytes of an arbitrary slab regardless of its type. Useful for
340    /// callers that want to do their own decoding (e.g. zero-copy
341    /// `bytemuck::cast_slice` on aligned input; multi-byte slabs are
342    /// always little-endian on disk).
343    pub fn read_raw(&self, p: SlabPlaceholder) -> Result<&'a [u8], DecodeError> {
344        Ok(self.slab_at(p)?.bytes)
345    }
346}
347
348/// Error from [`ParsedFile::parse`] and the `ParsedFile::read*` resolvers.
349#[derive(Debug, Error)]
350pub enum DecodeError {
351    /// JSLB header / slab table is malformed.
352    #[error("JSLB parse error: {0}")]
353    Parse(#[from] ParseError),
354    /// A [`SlabPlaceholder`] referenced an index past the end of the slab table.
355    #[error("slab index {index} out of range (slab count: {slab_count})")]
356    SlabIndexOutOfRange {
357        /// The out-of-range placeholder index.
358        index: usize,
359        /// The file's total slab count.
360        slab_count: usize,
361    },
362    /// A typed read was performed against a slab of the wrong type.
363    #[error("slab {index} has type {found} but caller expected {expected}")]
364    SlabTypeMismatch {
365        /// Slab table index of the offending slab.
366        index: usize,
367        /// The type the caller asked for.
368        expected: SlabType,
369        /// The type the slab actually has on disk.
370        found: SlabType,
371    },
372}
373
374/// Streaming reader exposing only the root JSON slab of a JSLB byte stream.
375///
376/// This can be used by consumers which are only interested in the JSON
377/// at the root of the JSLB file and not in anything else.
378///
379/// Useful for compressed JSLB files (e.g. .jslb.gz) because you'll only
380/// end up compressing the start of the file, provided the root JSON slab
381/// is the first slab.
382#[derive(Debug)]
383pub struct RootJsonReader<R: Read> {
384    inner: R,
385    remaining: u64,
386}
387
388impl<R: Read> RootJsonReader<R> {
389    /// Wrap `inner`, reading the fixed header and slab table so that
390    /// subsequent reads yield exactly the root JSON slab's bytes.
391    ///
392    /// Fails with [`io::ErrorKind::InvalidData`] if the header or slab
393    /// table is malformed, if the designated root slab is not
394    /// [`SlabType::Json`], or if the root slab's byte range overlaps the
395    /// slab table. Fails with [`io::ErrorKind::UnexpectedEof`] if the
396    /// stream ends before the root slab's start offset.
397    pub fn new(mut inner: R) -> io::Result<Self> {
398        let dir = SlabDirectory::read(&mut inner)?;
399        let consumed = dir.header_and_table_size();
400        let root = *dir.root_entry();
401
402        if root.slab_type != SlabType::Json {
403            return Err(io::Error::new(
404                io::ErrorKind::InvalidData,
405                "JSLB root slab is not TYPE_JSON",
406            ));
407        }
408        if root.start_offset < consumed {
409            return Err(io::Error::new(
410                io::ErrorKind::InvalidData,
411                "JSLB root slab overlaps the slab table",
412            ));
413        }
414
415        let to_skip = root.start_offset - consumed;
416        let skipped = io::copy(&mut (&mut inner).take(to_skip), &mut io::sink())?;
417        if skipped < to_skip {
418            return Err(io::Error::new(
419                io::ErrorKind::UnexpectedEof,
420                "JSLB stream ended before the root JSON slab",
421            ));
422        }
423
424        Ok(Self {
425            inner,
426            remaining: root.byte_length,
427        })
428    }
429}
430
431impl<R: Read> Read for RootJsonReader<R> {
432    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
433        if self.remaining == 0 {
434            return Ok(0);
435        }
436        let take = (buf.len() as u64).min(self.remaining) as usize;
437        let n = self.inner.read(&mut buf[..take])?;
438        self.remaining -= n as u64;
439        Ok(n)
440    }
441}