Skip to main content

fprint_fp3/
gvariant.rs

1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! A minimal, hand-rolled GVariant serializer/parser — only the type-shapes the FP3
6//! container needs, laid out in GVariant *normal form*, little-endian.
7//!
8//! GVariant packs values without a framing byte per value: sizes are recovered from
9//! alignment plus a table of *framing offsets* appended to each variable-width container.
10//! This module implements that for the shapes FP3 uses — fixed scalars (`i`/`y`/`b`),
11//! strings (`s`), maybe-strings (`ms`), fixed-element arrays (`ai`), variable-element
12//! arrays (`a(aiaiai)`), tuples, and variants (`v`). There is no general type-driven
13//! engine; the codec names the shapes directly.
14//!
15//! ## Writing
16//!
17//! A [`Val`] is a fully serialized value carrying its alignment and whether its type is
18//! fixed-width (the two facts a parent container needs to place it and to decide framing).
19//! Values compose bottom-up — [`tuple`]/[`array`] take their children and emit the padded
20//! body plus the framing-offset table.
21//!
22//! ## Reading
23//!
24//! The reader is a set of bounds-checked extractors. [`walk_tuple`] splits a tuple's bytes
25//! into its member slices given a static description of the members; the scalar/string/array
26//! readers turn a member slice into a value. Every access is checked and yields
27//! [`Fp3Error::Malformed`] rather than panicking.
28//!
29//! **The reader cannot recurse**: the codec names each shape it reads, and FP3's grammar is
30//! depth-fixed — a `Template::Raw` payload's bytes are never parsed, and the NBIS payload
31//! bottoms out at `(aiaiai)`. Nesting depth is therefore not an input, and no recursion limit
32//! exists or is needed. Attacker-controlled *breadth* is bounded instead by
33//! [`read_var_array`]'s disjointness rule.
34
35use crate::error::{Fp3Error, Result};
36
37// ---- framing arithmetic ---------------------------------------------------------------
38
39/// Round `pos` up to the next multiple of `align` (a power of two: 1, 4, or 8 here).
40fn align_up(pos: usize, align: usize) -> usize {
41    (pos + align - 1) & !(align - 1)
42}
43
44/// Pad `buf` with zero bytes until its length is a multiple of `align`.
45fn pad(buf: &mut Vec<u8>, align: usize) {
46    while buf.len() % align != 0 {
47        buf.push(0);
48    }
49}
50
51/// The width (in bytes) GVariant uses to store framing offsets in a container of the given
52/// total `size`: the smallest of 1/2/4/8 that can address any byte in it. Zero for an empty
53/// container. This is the reader's rule — the inverse of [`chosen_offset_size`].
54fn offset_size(size: usize) -> usize {
55    if size == 0 {
56        0
57    } else if size <= 0xff {
58        1
59    } else if size <= 0xffff {
60        2
61    } else if size <= 0xffff_ffff {
62        4
63    } else {
64        8
65    }
66}
67
68/// The writer's dual of [`offset_size`]: the smallest offset width such that a body of
69/// `body` bytes plus `n` framing offsets of that width still fits in the width itself
70/// (adding the table can push the total across a boundary, so the choice is made against
71/// the *grown* size — GLib's `gvs_calculate_total_size`).
72fn chosen_offset_size(body: usize, n: usize) -> usize {
73    if n == 0 {
74        0
75    } else if body + n <= 0xff {
76        1
77    } else if body + 2 * n <= 0xffff {
78        2
79    } else if body + 4 * n <= 0xffff_ffff {
80        4
81    } else {
82        8
83    }
84}
85
86/// Append `value` as a little-endian offset of `width` bytes.
87fn push_offset(buf: &mut Vec<u8>, value: usize, width: usize) {
88    let le = (value as u64).to_le_bytes();
89    buf.extend_from_slice(&le[..width]);
90}
91
92/// Read a little-endian framing offset of `width` bytes at `pos`, bounds-checked.
93fn read_offset(slice: &[u8], pos: usize, width: usize) -> Result<usize> {
94    let end = pos
95        .checked_add(width)
96        .ok_or(Fp3Error::Malformed("offset position overflow"))?;
97    let raw = slice
98        .get(pos..end)
99        .ok_or(Fp3Error::Malformed("framing offset out of range"))?;
100    let mut acc = 0u64;
101    for (i, &b) in raw.iter().enumerate() {
102        acc |= u64::from(b) << (8 * i);
103    }
104    Ok(acc as usize)
105}
106
107// ---- writing --------------------------------------------------------------------------
108
109/// A serialized GVariant value: its bytes, its alignment, and whether its *type* is
110/// fixed-width. Parents read `align` to place it and `fixed` to decide whether it needs a
111/// framing offset.
112pub(crate) struct Val {
113    bytes: Vec<u8>,
114    align: usize,
115    fixed: bool,
116}
117
118impl Val {
119    /// Consume the value, yielding its serialized bytes.
120    pub(crate) fn into_bytes(self) -> Vec<u8> {
121        self.bytes
122    }
123}
124
125/// A GVariant `i` (int32): 4 bytes little-endian, alignment 4, fixed-width.
126pub(crate) fn int32(v: i32) -> Val {
127    Val {
128        bytes: v.to_le_bytes().to_vec(),
129        align: 4,
130        fixed: true,
131    }
132}
133
134/// A GVariant `y` (byte): alignment 1, fixed-width.
135pub(crate) fn byte(v: u8) -> Val {
136    Val {
137        bytes: vec![v],
138        align: 1,
139        fixed: true,
140    }
141}
142
143/// A GVariant `b` (boolean): one byte `0x00`/`0x01`, alignment 1, fixed-width.
144pub(crate) fn boolean(v: bool) -> Val {
145    Val {
146        bytes: vec![u8::from(v)],
147        align: 1,
148        fixed: true,
149    }
150}
151
152/// A GVariant `s` (string): the UTF-8 bytes plus one `0x00` terminator, alignment 1.
153pub(crate) fn string(s: &str) -> Val {
154    let mut bytes = s.as_bytes().to_vec();
155    bytes.push(0);
156    Val {
157        bytes,
158        align: 1,
159        fixed: false,
160    }
161}
162
163/// A GVariant `ms` (maybe of a variable-size string). `Nothing` is zero bytes; `Just` is
164/// the string's serialized bytes followed by one extra `0x00`.
165pub(crate) fn maybe_string(s: Option<&str>) -> Val {
166    match s {
167        None => Val {
168            bytes: Vec::new(),
169            align: 1,
170            fixed: false,
171        },
172        Some(s) => {
173            let mut bytes = s.as_bytes().to_vec();
174            bytes.push(0); // the string's own terminator
175            bytes.push(0); // the maybe's presence byte
176            Val {
177                bytes,
178                align: 1,
179                fixed: false,
180            }
181        }
182    }
183}
184
185/// The empty `a{sv}` reserved vardict: always zero bytes, alignment 8.
186pub(crate) fn empty_vardict() -> Val {
187    Val {
188        bytes: Vec::new(),
189        align: 8,
190        fixed: false,
191    }
192}
193
194/// A GVariant `ai` (array of fixed-width int32): elements concatenated, no framing table
195/// (their count is recovered as `size / 4`). Alignment 4.
196pub(crate) fn int32_array(xs: &[i32]) -> Val {
197    let mut bytes = Vec::with_capacity(xs.len() * 4);
198    for &x in xs {
199        bytes.extend_from_slice(&x.to_le_bytes());
200    }
201    Val {
202        bytes,
203        align: 4,
204        fixed: false,
205    }
206}
207
208/// A GVariant `a T` for variable-width `T`: each element padded to `elem_align`, then a
209/// framing-offset table giving each element's end position (in element order). An empty
210/// array is zero bytes.
211pub(crate) fn array(elems: Vec<Val>, elem_align: usize) -> Val {
212    if elems.is_empty() {
213        return Val {
214            bytes: Vec::new(),
215            align: elem_align,
216            fixed: false,
217        };
218    }
219    let mut body = Vec::new();
220    let mut ends = Vec::with_capacity(elems.len());
221    for e in &elems {
222        pad(&mut body, elem_align);
223        body.extend_from_slice(&e.bytes);
224        ends.push(body.len());
225    }
226    let width = chosen_offset_size(body.len(), ends.len());
227    for &end in &ends {
228        push_offset(&mut body, end, width);
229    }
230    Val {
231        bytes: body,
232        align: elem_align,
233        fixed: false,
234    }
235}
236
237/// A GVariant tuple `(...)`: members laid out in order, each padded to its alignment; a
238/// framing offset (its end position) recorded for every variable-width member except the
239/// last, then appended in *reverse* member order. An all-fixed tuple is padded to its own
240/// alignment and is itself fixed-width; a variable-width tuple whose content is empty (its
241/// single member an empty array) serializes to zero bytes.
242pub(crate) fn tuple(members: Vec<Val>, align: usize) -> Val {
243    let len = members.len();
244    let mut body = Vec::new();
245    let mut var_ends = Vec::new();
246    for (i, m) in members.iter().enumerate() {
247        pad(&mut body, m.align);
248        body.extend_from_slice(&m.bytes);
249        if !m.fixed && i + 1 != len {
250            var_ends.push(body.len());
251        }
252    }
253    if members.iter().all(|m| m.fixed) {
254        pad(&mut body, align);
255        return Val {
256            bytes: body,
257            align,
258            fixed: true,
259        };
260    }
261    let width = chosen_offset_size(body.len(), var_ends.len());
262    for &end in var_ends.iter().rev() {
263        push_offset(&mut body, end, width);
264    }
265    Val {
266        bytes: body,
267        align,
268        fixed: false,
269    }
270}
271
272/// A GVariant `v` (variant): the child's serialized bytes, a `0x00` separator, then the
273/// child's type-signature ASCII (no trailing NUL). Alignment 8.
274pub(crate) fn variant(child: Val, signature: &[u8]) -> Val {
275    let mut bytes = child.bytes;
276    bytes.push(0);
277    bytes.extend_from_slice(signature);
278    Val {
279        bytes,
280        align: 8,
281        fixed: false,
282    }
283}
284
285/// A `v` whose already-serialized bytes are supplied verbatim (a driver's opaque, standalone
286/// variant preserved byte-for-byte). Alignment 8.
287pub(crate) fn raw_variant(bytes: Vec<u8>) -> Val {
288    Val {
289        bytes,
290        align: 8,
291        fixed: false,
292    }
293}
294
295// ---- reading --------------------------------------------------------------------------
296
297/// A static description of one tuple member: its alignment, and its fixed size if the type
298/// is fixed-width (`None` for variable-width members).
299pub(crate) struct Spec {
300    align: usize,
301    size: Option<usize>,
302}
303
304impl Spec {
305    /// A fixed-width member of the given alignment and byte size.
306    pub(crate) const fn fixed(align: usize, size: usize) -> Spec {
307        Spec {
308            align,
309            size: Some(size),
310        }
311    }
312
313    /// A variable-width member of the given alignment.
314    pub(crate) const fn var(align: usize) -> Spec {
315        Spec { align, size: None }
316    }
317}
318
319/// Split a tuple's serialized `slice` into its member byte-slices, given the members'
320/// static [`Spec`]s. Fixed members are read at their size; variable non-final members are
321/// bounded by framing offsets (stored in reverse at the tail); the final variable member
322/// runs to the start of the framing table.
323pub(crate) fn walk_tuple<'a>(slice: &'a [u8], specs: &[Spec]) -> Result<Vec<&'a [u8]>> {
324    let size = slice.len();
325    let len = specs.len();
326    let n_offsets = specs
327        .iter()
328        .enumerate()
329        .filter(|(i, s)| s.size.is_none() && *i + 1 != len)
330        .count();
331    let width = offset_size(size);
332    let table = n_offsets
333        .checked_mul(width)
334        .ok_or(Fp3Error::Malformed("tuple offset table overflow"))?;
335    let body_size = size
336        .checked_sub(table)
337        .ok_or(Fp3Error::Malformed("tuple shorter than its framing table"))?;
338
339    let mut out = Vec::with_capacity(len);
340    let mut pos = 0usize;
341    let mut consumed = 0usize;
342    for (i, spec) in specs.iter().enumerate() {
343        pos = align_up(pos, spec.align);
344        let end = match spec.size {
345            Some(sz) => pos + sz,
346            None if i + 1 == len => body_size,
347            None => {
348                consumed += 1;
349                read_offset(slice, size - consumed * width, width)?
350            }
351        };
352        if pos > end || end > slice.len() {
353            return Err(Fp3Error::Malformed("tuple member out of range"));
354        }
355        out.push(&slice[pos..end]);
356        pos = end;
357    }
358    Ok(out)
359}
360
361/// Split a `v`'s serialized `slice` into `(child_value, signature)`. The signature is the
362/// tail after the final `0x00` (signatures contain no NUL, so the last `0x00` is the
363/// separator); the child value is everything before it.
364pub(crate) fn split_variant(slice: &[u8]) -> Result<(&[u8], &[u8])> {
365    let sep = slice
366        .iter()
367        .rposition(|&b| b == 0)
368        .ok_or(Fp3Error::Malformed("variant missing signature separator"))?;
369    Ok((&slice[..sep], &slice[sep + 1..]))
370}
371
372/// Read a GVariant `i` (int32) from a 4-byte member slice.
373pub(crate) fn read_i32(slice: &[u8]) -> Result<i32> {
374    let bytes: [u8; 4] = slice
375        .get(..4)
376        .and_then(|s| s.try_into().ok())
377        .ok_or(Fp3Error::Malformed("int32 too short"))?;
378    Ok(i32::from_le_bytes(bytes))
379}
380
381/// Read a GVariant `y` (byte) from a 1-byte member slice.
382pub(crate) fn read_byte(slice: &[u8]) -> Result<u8> {
383    slice
384        .first()
385        .copied()
386        .ok_or(Fp3Error::Malformed("byte member empty"))
387}
388
389/// Read a GVariant `b` (boolean) from a 1-byte member slice (nonzero ⇒ true).
390pub(crate) fn read_bool(slice: &[u8]) -> Result<bool> {
391    Ok(read_byte(slice)? != 0)
392}
393
394/// Read a GVariant `s` (string): UTF-8 bytes followed by a `0x00` terminator.
395pub(crate) fn read_string(slice: &[u8]) -> Result<String> {
396    let utf8 = slice
397        .strip_suffix(&[0])
398        .ok_or(Fp3Error::Malformed("string not nul-terminated"))?;
399    core::str::from_utf8(utf8)
400        .map(str::to_owned)
401        .map_err(|_| Fp3Error::Malformed("string not valid utf-8"))
402}
403
404/// Read a GVariant `ms` (maybe-string): `Nothing` (empty slice) ⇒ `None`; `Just` ⇒ the
405/// string with its trailing maybe-presence byte stripped.
406pub(crate) fn read_maybe_string(slice: &[u8]) -> Result<Option<String>> {
407    if slice.is_empty() {
408        return Ok(None);
409    }
410    let inner = &slice[..slice.len() - 1];
411    Ok(Some(read_string(inner)?))
412}
413
414/// Read a GVariant `ai` (array of int32) from a member slice whose length is a multiple of 4.
415pub(crate) fn read_i32_array(slice: &[u8]) -> Result<Vec<i32>> {
416    if slice.len() % 4 != 0 {
417        return Err(Fp3Error::Malformed("int32 array size not a multiple of 4"));
418    }
419    slice
420        .chunks_exact(4)
421        .map(|c| {
422            let bytes: [u8; 4] = c
423                .try_into()
424                .map_err(|_| Fp3Error::Malformed("int32 array chunk not 4 bytes"))?;
425            Ok(i32::from_le_bytes(bytes))
426        })
427        .collect()
428}
429
430/// Read a GVariant `a T` for variable-width `T`, decoding each element slice with `f`.
431///
432/// The framing table sits at the tail: its last offset marks the end of the final element
433/// (and the start of the table), from which the element count follows. An empty array is
434/// zero bytes; the degenerate one-byte `0x00` tuple-minimum encoding of an empty array
435/// (whose final offset reads as 0) is likewise treated as empty.
436pub(crate) fn read_var_array<T, F>(slice: &[u8], elem_align: usize, mut f: F) -> Result<Vec<T>>
437where
438    F: FnMut(&[u8]) -> Result<T>,
439{
440    if slice.is_empty() {
441        return Ok(Vec::new());
442    }
443    let size = slice.len();
444    let width = offset_size(size);
445    let last_end = read_offset(slice, size - width, width)?;
446    if last_end == 0 {
447        return Ok(Vec::new());
448    }
449    if last_end > size {
450        return Err(Fp3Error::Malformed("array framing offset past end"));
451    }
452    let table = size - last_end;
453    if table % width != 0 {
454        return Err(Fp3Error::Malformed("array framing table misaligned"));
455    }
456    let n = table / width;
457
458    let mut out = Vec::with_capacity(n);
459    let mut prev = 0usize;
460    for k in 0..n {
461        let end = read_offset(slice, last_end + k * width, width)?;
462        let start = align_up(prev, elem_align);
463        if start > end || end > last_end {
464            return Err(Fp3Error::Malformed("array element out of range"));
465        }
466        out.push(f(&slice[start..end])?);
467        prev = end;
468    }
469    Ok(out)
470}
471
472#[cfg(test)]
473mod tests {
474    use super::*;
475    use crate::codec::TOP_SPECS;
476
477    /// A real libfprint NBIS blob, magic included — the only input here that is not hand-framed.
478    const FIXTURE: &[u8] = include_bytes!("../tests/fixtures/libfprint_virtual_image_nbis.fp3");
479
480    /// Decode an array of variable-width elements into each element's length. The lengths are
481    /// what the framing arithmetic decides, so they are what these tests assert on.
482    fn elem_lens(slice: &[u8], elem_align: usize) -> Result<Vec<usize>> {
483        read_var_array(slice, elem_align, |s| Ok(s.len()))
484    }
485
486    // ---- the framing-offset width: writer and reader must agree -----------------------
487
488    /// **[`chosen_offset_size`] and [`offset_size`] are duals**: the width the writer picks for
489    /// a body plus `n` offsets is the width the reader recovers from the resulting total size.
490    /// The two are computed from different quantities — the writer from the body it has, the
491    /// reader from the size it finds — and the table's own bytes can push the total across a
492    /// power-of-two boundary, which is the case that makes them non-obvious.
493    #[test]
494    fn writer_and_reader_agree_on_offset_width() {
495        for n in [1usize, 2, 3, 17, 255] {
496            for body in [
497                0usize, 1, 200, 253, 254, 255, 256, 0xfffd, 0xfffe, 0xffff, 0x1_0000,
498            ] {
499                let width = chosen_offset_size(body, n);
500                let total = body + n * width;
501                assert_eq!(
502                    offset_size(total),
503                    width,
504                    "body {body}, n {n}: writer chose {width}, reader recovers {}",
505                    offset_size(total)
506                );
507            }
508        }
509    }
510
511    // ---- read_var_array: the disjointness rule ----------------------------------------
512
513    /// **The `start > end` check is what keeps array elements disjoint.** An offset table whose
514    /// entries run backwards asks for element `[8..4]` — a reversed range, which slicing would
515    /// panic on. It is rejected instead.
516    ///
517    /// Disjointness — not this check — is what bounds the total work: `prev = end` each
518    /// iteration, so the element slices tile the body in order and their lengths sum to at most
519    /// the body's size, however many offsets the table holds.
520    #[test]
521    fn overlapping_array_elements_are_rejected() {
522        // A 12-byte body (three int32s) written by this module, plus a hand-built 3-entry
523        // table. The last entry is `last_end` (12), which is what marks the table's start; the
524        // first two run backwards, so element 1 would start at 8 and end at 4.
525        let mut blob = int32_array(&[1, 2, 3]).into_bytes();
526        assert_eq!(blob.len(), 12);
527        blob.extend_from_slice(&[8, 4, 12]);
528
529        assert!(matches!(
530            elem_lens(&blob, 4),
531            Err(Fp3Error::Malformed("array element out of range"))
532        ));
533    }
534
535    /// An element whose offset ends past the final element's end is out of range, even though it
536    /// is still inside the slice — the table's own bytes are not element data.
537    #[test]
538    fn array_element_ending_past_the_body_is_rejected() {
539        let mut blob = int32_array(&[1, 2, 3]).into_bytes();
540        blob.extend_from_slice(&[13, 12]);
541
542        assert!(matches!(
543            elem_lens(&blob, 4),
544            Err(Fp3Error::Malformed("array element out of range"))
545        ));
546    }
547
548    /// A table whose every entry points at the body's end is **accepted**, and costs one body's
549    /// worth of work: element 0 spans the body, and each later element is empty because `prev`
550    /// has already reached the end. It is pinned here because it is the shape that looks like a
551    /// blowup and is not one.
552    #[test]
553    fn array_elements_all_pointing_at_the_body_end_collapse_to_empty() {
554        let mut blob = int32_array(&[1, 2, 3]).into_bytes();
555        blob.extend_from_slice(&[12, 12, 12]);
556
557        assert_eq!(elem_lens(&blob, 4).unwrap(), vec![12, 0, 0]);
558    }
559
560    /// The final offset names the table's start; past the slice's end it is nonsense.
561    #[test]
562    fn array_framing_offset_past_the_end_is_rejected() {
563        assert!(matches!(
564            elem_lens(&[0xff, 0xff, 0xff, 0xff], 4),
565            Err(Fp3Error::Malformed("array framing offset past end"))
566        ));
567    }
568
569    /// The table is a whole number of offsets. A `last_end` leaving a remainder is malformed.
570    /// Reaching this needs a 2-byte offset width, so the slice must exceed 255 bytes.
571    #[test]
572    fn array_framing_table_misaligned_is_rejected() {
573        let mut blob = vec![0u8; 300];
574        // Offset width is 2 here; a `last_end` of 299 leaves a 1-byte table.
575        blob[298..300].copy_from_slice(&299u16.to_le_bytes());
576
577        assert!(matches!(
578            elem_lens(&blob, 4),
579            Err(Fp3Error::Malformed("array framing table misaligned"))
580        ));
581    }
582
583    /// Zero bytes is the empty array, and so is the degenerate encoding whose final offset reads
584    /// as zero. Neither is an error.
585    #[test]
586    fn empty_arrays_decode_to_no_elements() {
587        assert_eq!(elem_lens(&[], 4).unwrap(), Vec::<usize>::new());
588        assert_eq!(elem_lens(&[0], 4).unwrap(), Vec::<usize>::new());
589    }
590
591    // ---- walk_tuple ------------------------------------------------------------------
592
593    /// A tuple's framing table cannot be larger than the tuple itself.
594    #[test]
595    fn tuple_shorter_than_its_framing_table_is_rejected() {
596        // Four variable members: three carry offsets (the last never does). Two bytes cannot
597        // hold a three-offset table.
598        let specs = [Spec::var(1), Spec::var(1), Spec::var(1), Spec::var(1)];
599        assert!(matches!(
600            walk_tuple(&[0, 0], &specs),
601            Err(Fp3Error::Malformed("tuple shorter than its framing table"))
602        ));
603    }
604
605    /// A member offset outside the tuple's bytes is rejected rather than sliced.
606    #[test]
607    fn tuple_member_out_of_range_is_rejected() {
608        // Two members, one offset (for member 0) in the last byte, pointing past the end.
609        let specs = [Spec::var(1), Spec::var(1)];
610        assert!(matches!(
611            walk_tuple(&[0, 0, 0xff], &specs),
612            Err(Fp3Error::Malformed("tuple member out of range"))
613        ));
614    }
615
616    /// A fixed member reaching past the tuple's bytes is rejected, not read out of bounds.
617    #[test]
618    fn tuple_fixed_member_past_the_end_is_rejected() {
619        let specs = [Spec::fixed(4, 4)];
620        assert!(matches!(
621            walk_tuple(&[0, 0], &specs),
622            Err(Fp3Error::Malformed("tuple member out of range"))
623        ));
624    }
625
626    /// **Every prefix of a real libfprint blob either parses or errors — none panics.** The
627    /// top-level shape is the production [`TOP_SPECS`], so this walks the same arithmetic
628    /// `from_bytes` does, over every truncation point the wire can present.
629    #[test]
630    fn truncated_tuple_at_every_prefix_is_rejected_not_panicked() {
631        let body = &FIXTURE[crate::MAGIC.len()..];
632        for n in 0..body.len() {
633            // The property is total: no prefix may panic, and every member slice a successful
634            // walk yields must lie inside the prefix it came from.
635            if let Ok(members) = walk_tuple(&body[..n], &TOP_SPECS) {
636                for m in members {
637                    assert!(
638                        m.len() <= n,
639                        "member longer than the {n}-byte prefix it came from"
640                    );
641                }
642            }
643        }
644        // The untruncated body is the control: it must actually parse.
645        assert!(walk_tuple(body, &TOP_SPECS).is_ok());
646    }
647
648    // ---- scalar and string readers ---------------------------------------------------
649
650    #[test]
651    fn strings_must_be_nul_terminated_and_utf8() {
652        assert_eq!(read_string(b"ok\0").unwrap(), "ok");
653        assert!(matches!(
654            read_string(b"no-terminator"),
655            Err(Fp3Error::Malformed("string not nul-terminated"))
656        ));
657        assert!(matches!(
658            read_string(&[0xff, 0xfe, 0]),
659            Err(Fp3Error::Malformed("string not valid utf-8"))
660        ));
661        // The empty string is a lone terminator, not an error.
662        assert_eq!(read_string(b"\0").unwrap(), "");
663    }
664
665    /// `ms` distinguishes absent from empty: no bytes is `Nothing`; a bare presence byte is
666    /// `Just("")`.
667    #[test]
668    fn maybe_strings_separate_nothing_from_empty() {
669        assert_eq!(read_maybe_string(&[]).unwrap(), None);
670        assert_eq!(read_maybe_string(&[0, 0]).unwrap(), Some(String::new()));
671        assert_eq!(read_maybe_string(b"hi\0\0").unwrap(), Some("hi".into()));
672    }
673
674    #[test]
675    fn int32_arrays_must_be_a_whole_number_of_elements() {
676        assert_eq!(read_i32_array(&[]).unwrap(), Vec::<i32>::new());
677        assert_eq!(read_i32_array(&1i32.to_le_bytes()).unwrap(), vec![1]);
678        assert!(matches!(
679            read_i32_array(&[0, 0, 0]),
680            Err(Fp3Error::Malformed("int32 array size not a multiple of 4"))
681        ));
682    }
683
684    #[test]
685    fn int32_shorter_than_four_bytes_is_rejected() {
686        assert!(matches!(
687            read_i32(&[0, 0, 0]),
688            Err(Fp3Error::Malformed("int32 too short"))
689        ));
690        assert_eq!(read_i32(&(-1i32).to_le_bytes()).unwrap(), -1);
691    }
692
693    #[test]
694    fn empty_scalar_members_are_rejected() {
695        assert!(matches!(
696            read_byte(&[]),
697            Err(Fp3Error::Malformed("byte member empty"))
698        ));
699        assert!(matches!(
700            read_bool(&[]),
701            Err(Fp3Error::Malformed("byte member empty"))
702        ));
703        // Any nonzero byte is true — GVariant normal form says 0/1, the reader is liberal.
704        assert!(read_bool(&[2]).unwrap());
705    }
706
707    /// A `v` carries its signature after the last `0x00`. With no `0x00` at all there is no
708    /// signature to find.
709    #[test]
710    fn variant_without_a_separator_is_rejected() {
711        assert!(matches!(
712            split_variant(b"nope"),
713            Err(Fp3Error::Malformed("variant missing signature separator"))
714        ));
715        let (child, sig) = split_variant(b"hi\0\0s").unwrap();
716        assert_eq!((child, sig), (b"hi\0".as_slice(), b"s".as_slice()));
717    }
718
719    // ---- writer/reader round-trips ---------------------------------------------------
720
721    /// The writers emit what the readers expect, for the shapes with framing tables.
722    #[test]
723    fn hand_framed_values_read_back() {
724        assert_eq!(read_i32(&int32(-7).into_bytes()).unwrap(), -7);
725        assert_eq!(read_byte(&byte(9).into_bytes()).unwrap(), 9);
726        assert!(read_bool(&boolean(true).into_bytes()).unwrap());
727        assert_eq!(read_string(&string("x").into_bytes()).unwrap(), "x");
728        assert_eq!(
729            read_maybe_string(&maybe_string(Some("y")).into_bytes()).unwrap(),
730            Some("y".into())
731        );
732        assert_eq!(
733            read_maybe_string(&maybe_string(None).into_bytes()).unwrap(),
734            None
735        );
736        assert_eq!(
737            read_i32_array(&int32_array(&[1, -2, 3]).into_bytes()).unwrap(),
738            vec![1, -2, 3]
739        );
740
741        // An array of three variable-width elements of differing lengths, through the writer.
742        let elems = vec![
743            int32_array(&[1]),
744            int32_array(&[2, 3]),
745            int32_array(&[4, 5, 6]),
746        ];
747        let blob = array(elems, 4).into_bytes();
748        assert_eq!(elem_lens(&blob, 4).unwrap(), vec![4, 8, 12]);
749    }
750
751    /// An all-fixed tuple carries no framing table; a variable one is split by its offsets.
752    #[test]
753    fn tuples_round_trip_through_their_framing() {
754        let blob = tuple(vec![int32(1), byte(2)], 4).into_bytes();
755        let members = walk_tuple(&blob, &[Spec::fixed(4, 4), Spec::fixed(1, 1)]).unwrap();
756        assert_eq!(read_i32(members[0]).unwrap(), 1);
757        assert_eq!(read_byte(members[1]).unwrap(), 2);
758
759        let blob = tuple(vec![string("ab"), string("c")], 1).into_bytes();
760        let members = walk_tuple(&blob, &[Spec::var(1), Spec::var(1)]).unwrap();
761        assert_eq!(read_string(members[0]).unwrap(), "ab");
762        assert_eq!(read_string(members[1]).unwrap(), "c");
763    }
764}