mlt_core/dump/
model.rs

1//! Data model for the annotated binary dump (see [`crate::dump`]).
2
3use std::fmt::{Display, Formatter, Result as FmtResult};
4
5use serde::ser::SerializeStruct as _;
6use serde::{Serialize, Serializer};
7
8#[cfg(feature = "unstable-v2")]
9use crate::codecs::presence_coding::PresenceCoding;
10#[cfg(feature = "unstable-v2")]
11use crate::wire::Alp;
12use crate::wire::StreamMeta;
13
14/// Whether a region is tile metadata or an opaque data payload.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
16#[serde(rename_all = "camelCase")]
17pub enum RegionKind {
18    /// Framing, schema, or stream-header bytes, annotated byte- and bit-for-byte.
19    Meta,
20    /// A stream payload, rendered as raw hex plus best-effort decoded values.
21    DataBlob,
22}
23
24/// How a [`RegionKind::DataBlob`] payload is decoded for display.
25///
26/// Best-effort: on any decode error the renderer falls back to raw hex.
27#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
28#[serde(tag = "kind", rename_all = "camelCase")]
29pub enum DecodeHint {
30    /// Nullability bitmap (byte-RLE -> packed bits).
31    Presence,
32    /// Boolean data stream (byte-RLE -> bools).
33    Bool,
34    /// Signed 32-bit integers (`i8`/`i32` columns).
35    I32,
36    /// Unsigned 32-bit integers (`u8`/`u32` columns, offsets, lengths).
37    U32,
38    /// The geometry types stream: `u32`s that each name a [`GeometryType`](crate::GeometryType).
39    GeometryType,
40    /// Signed 64-bit integers (`i64` columns).
41    I64,
42    /// Framed, Exception-Free ALP offsets, put back on their frame of reference.
43    #[cfg(feature = "unstable-v2")]
44    Alp(#[serde(serialize_with = "serialize_alp")] Alp),
45    /// Unsigned 64-bit integers (`u64` columns, 64-bit ids).
46    U64,
47    /// 32-bit floats.
48    F32,
49    /// 64-bit floats.
50    F64,
51    /// Opaque bytes (string / dictionary / FSST payloads); shown as hex + UTF-8 preview.
52    Bytes,
53    /// A raw LSB0 bitfield, not a stream: `ceil(num_values/8)` packed bytes.
54    #[cfg(feature = "unstable-v2")]
55    PackedBits,
56    /// Presence bits that are not laid out as bits: runs, or a list of indices.
57    #[cfg(feature = "unstable-v2")]
58    PresenceCoded(PresenceCoding),
59}
60
61/// Framed, Exception-Free ALP's parameters flattened beside the hint's tag, keeping `Alp`'s fields crate-private.
62#[cfg(feature = "unstable-v2")]
63fn serialize_alp<S: Serializer>(alp: &Alp, s: S) -> Result<S::Ok, S::Error> {
64    let mut st = s.serialize_struct("Alp", 3)?;
65    st.serialize_field("e", &alp.scale.e)?;
66    st.serialize_field("f", &alp.scale.f)?;
67    st.serialize_field("base", &alp.base)?;
68    st.end()
69}
70
71/// One sub-field of a bit-packed byte, e.g. a nibble of `stream_type`.
72#[derive(Debug, Clone, Serialize)]
73pub struct BitField {
74    /// Inclusive high bit index (7..=0, MSB first).
75    hi: u8,
76    /// Inclusive low bit index.
77    lo: u8,
78    /// The extracted field value, shifted down to bit 0.
79    #[serde(serialize_with = "serialize_as_number")]
80    raw: u64,
81    /// Human-readable meaning, e.g. `"physical = VarInt"`.
82    meaning: String,
83}
84
85impl BitField {
86    /// One field of a packed byte, located by the same mask constant the parser reads it
87    /// with, so the dump cannot drift from the wire format.
88    ///
89    /// `raw` is the masked bits shifted down to bit 0, so it renders as the field's own
90    /// value rather than its in-byte position. `mask` must be one contiguous run of bits.
91    pub fn mask(mask: u8, byte: u8, meaning: impl Into<String>) -> Self {
92        let (hi, lo) = mask_bounds(mask);
93        Self {
94            hi,
95            lo,
96            raw: u64::from((byte & mask) >> lo),
97            meaning: meaning.into(),
98        }
99    }
100
101    /// A one-bit flag, worded as a phrase instead of a `0`/`1`.
102    ///
103    /// The renderer already prefixes every bit line with `bit N = V ->`, so `when_set`
104    /// and `when_clear` should say what the bit asserts about the tile rather than
105    /// repeat its value.
106    #[must_use]
107    pub fn flag(mask: u8, byte: u8, when_set: &str, when_clear: &str) -> Self {
108        debug_assert_eq!(mask.count_ones(), 1, "a flag occupies exactly one bit");
109        let meaning = if byte & mask == 0 {
110            when_clear
111        } else {
112            when_set
113        };
114        Self::mask(mask, byte, meaning)
115    }
116
117    /// What this field means in prose, without the `bit N = V ->` prefix
118    /// [`Display`] puts in front of it.
119    #[must_use]
120    pub fn meaning(&self) -> &str {
121        &self.meaning
122    }
123}
124
125impl Display for BitField {
126    /// `bit 7 = 1 -> meaning`, or `bits 6-4 = 011 -> meaning` for a multi-bit field.
127    ///
128    /// The value is printed as wide as the field, so the leading zeros of a nibble are
129    /// not mistaken for a narrower field. The caller adds any indent and color.
130    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
131        if self.hi == self.lo {
132            write!(f, "bit {}", self.hi)?;
133        } else {
134            write!(f, "bits {}-{}", self.hi, self.lo)?;
135        }
136        let width = usize::from(self.hi - self.lo + 1);
137        write!(f, " = {:0width$b} -> {}", self.raw, self.meaning)
138    }
139}
140
141/// Inclusive `(hi, lo)` bit indices spanned by `mask`.
142#[expect(
143    clippy::cast_possible_truncation,
144    reason = "a u8 mask spans at most 8 bits"
145)]
146fn mask_bounds(mask: u8) -> (u8, u8) {
147    debug_assert!(mask != 0, "a bit field needs at least one bit");
148    let lo = mask.trailing_zeros() as u8;
149    let hi = (u8::BITS - 1 - mask.leading_zeros()) as u8;
150    debug_assert_eq!(
151        u32::from(hi - lo) + 1,
152        mask.count_ones(),
153        "a bit field's mask must be one contiguous run of bits"
154    );
155    (hi, lo)
156}
157
158/// Stream metadata attached to a [`RegionKind::DataBlob`] so the renderer can decode it.
159#[derive(Debug, Clone, Copy)]
160pub struct BlobInfo {
161    pub meta: StreamMeta,
162    pub hint: DecodeHint,
163}
164
165impl Serialize for BlobInfo {
166    /// Flattens `meta` into display strings, so the wire vocabulary stays out of the JSON API.
167    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
168        let mut st = s.serialize_struct("BlobInfo", 5)?;
169        st.serialize_field("streamType", &self.meta.stream_type.to_string())?;
170        st.serialize_field("logical", &self.meta.encoding.logical.to_string())?;
171        st.serialize_field("physical", &self.meta.encoding.physical.to_string())?;
172        st.serialize_field("numValues", &self.meta.num_values)?;
173        st.serialize_field("hint", &self.hint)?;
174        st.end()
175    }
176}
177
178/// Serialize an offset or a count as a 32-bit number.
179///
180/// Only the payload values a tile actually holds are 64-bit, and a transport that maps
181/// 64-bit integers to `BigInt` would otherwise hand every offset across as one.
182fn serialize_as_number<T, S>(v: &T, s: S) -> Result<S::Ok, S::Error>
183where
184    T: Copy + TryInto<u32>,
185    S: Serializer,
186{
187    let n = (*v)
188        .try_into()
189        .map_err(|_| serde::ser::Error::custom("offset or count exceeds u32"))?;
190    s.serialize_u32(n)
191}
192
193/// A single annotated span of the tile buffer.
194///
195/// Emitted in pre-order. Containers bracket their children and may overlap them.
196/// Leaf regions partition the buffer exactly; the coverage test relies on this.
197#[derive(Debug, Clone, Serialize)]
198#[serde(rename_all = "camelCase")]
199pub struct Region {
200    /// Absolute byte offset into the tile buffer.
201    #[serde(serialize_with = "serialize_as_number")]
202    pub offset: usize,
203    #[serde(serialize_with = "serialize_as_number")]
204    pub len: usize,
205    /// Nesting depth, for indentation.
206    #[serde(serialize_with = "serialize_as_number")]
207    pub depth: usize,
208    /// Short label, e.g. `"column[2].type"` or `"num_values"`.
209    pub label: String,
210    /// Rendered scalar value (varint value, string, enum name), if any.
211    pub value: Option<String>,
212    /// Bit-level breakdown; empty unless this is a bit-packed byte.
213    pub bits: Vec<BitField>,
214    pub kind: RegionKind,
215    /// True for structural groups that span their children (excluded from coverage).
216    pub container: bool,
217    /// Present for `DataBlob` regions that carry decodable stream metadata.
218    pub blob: Option<BlobInfo>,
219}
220
221/// The full annotation of a tile: a flat, depth-tagged region list.
222#[derive(Serialize)]
223#[serde(rename_all = "camelCase")]
224pub struct DumpTree {
225    #[serde(serialize_with = "serialize_as_number")]
226    pub buf_len: usize,
227    /// Regions in pre-order (containers before their children).
228    pub regions: Vec<Region>,
229}
230
231/// Label of the synthetic leaf covering the bytes a bailed-out walk never reached.
232pub const UNANNOTATED: &str = "<unannotated>";
233
234/// The `idx`-th top-level layer's regions, or `None` when the tile has no such layer.
235///
236/// Containers span their children, so the layer is selected by byte range, not by depth.
237#[must_use]
238pub fn filter_layer(tree: &DumpTree, idx: usize) -> Option<DumpTree> {
239    let layer = tree
240        .regions
241        .iter()
242        .filter(|r| r.depth == 0 && r.container)
243        .nth(idx)?;
244    let start = layer.offset;
245    let end = layer.offset + layer.len;
246    let regions = tree
247        .regions
248        .iter()
249        .filter(|r| r.offset >= start && r.offset + r.len <= end)
250        .cloned()
251        .collect();
252    Some(DumpTree {
253        buf_len: tree.buf_len,
254        regions,
255    })
256}
mlt_core/dump/model.rs

mlt_core/dump/
model.rs
