Skip to main content

unityrs_core/walk/
boost.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPyBoost/TypeTreeHelper.cpp. See THIRD_PARTY_LICENSES.
2
3//! UnityPyBoost's reader (`UnityPyBoost/TypeTreeHelper.cpp:67-1056`), for
4//! objects with `byte_size > 0`. The rules, each pinned by a test (plan
5//! section 3.10, R1-R16): bounds checks `pos + n > end`, a length's before
6//! the bytes it counts; `align4` from the object's start with no bounds check; strings
7//! always aligned; `TypelessData` aligned only by its flag; the switch on the
8//! node's own kind first, and only a kind it does not handle (`Unknown`,
9//! `PPtr`, `Array`, `ReferencedObjectData`, `ManagedReferencesRegistry`) is an
10//! array when its first child is `Array` (R9); primitive and `pair` elements
11//! read as one run and align once, a `pair` run checking its arity before the
12//! first element, so even when empty; other elements read and align one by
13//! one; the `ManagedReferencesRegistry` scope; `ReferencedObject` data
14//! resolved through the file's ref types in UnityPyBoost's order (R14: no
15//! file, `ref_types` absent or not a list, no `type` read yet, a missing
16//! `class`/`ns`/`asm`, all `ref_type`; then an empty class or a matched ref
17//! type with no tree skips `data`; no match is `ref_type`; a `class` that is
18//! not a `Str` skips `data` when its Python object's size field is 0, else
19//! is `ref_type`, plan R14); `PyDict_SetItem`
20//! for repeated names; float32 widened (a signalling NaN quieted under
21//! [`super::FloatMode::UnityPy`]).
22//!
23//! Owner: package B.
24
25use std::sync::Arc;
26
27use bytes::Bytes;
28
29use super::dict::{FindError, RefIndex, RefNode, Trees, ref_tree};
30use super::{
31    FloatMode, Out, ReadCtx, ReadDetail, ReadError, ReadErrorKind, RefTypes, Work, charge_error,
32    f32_bits, int, limit_refused, py_size_field_is_zero, uint,
33};
34use crate::limits::MeteredVec;
35use crate::stream::Endian;
36use crate::typetree::{Kind, NodeId, Tree};
37use crate::value::{Parsed, PrimRun, Value, ValueBuilder};
38
39/// Reads one value from exactly `data` (the object's bytes). `TypelessData`
40/// and `vector<UInt8>` values are zero-copy slices of `data`.
41/// Its work is the open's, counted on `ctx.meter` whatever the outcome
42/// (the module docs of [`super`], "Work").
43pub fn read(data: &Bytes, tree: &Arc<Tree>, ctx: &ReadCtx<'_>) -> Result<Parsed, ReadError> {
44    read_with_fields(data, tree, ctx, None)
45}
46
47/// Read ordered class fields for a binding that must construct completed classes
48/// before surfacing a later reader error. Limits and allocation refusals remain
49/// immediate; the returned progress retains ordinary reader failures.
50pub fn read_object_fields(
51    data: &Bytes,
52    tree: &Arc<Tree>,
53    ctx: &ReadCtx<'_>,
54) -> Result<(Parsed, super::FieldProgress), ReadError> {
55    let mut progress = super::FieldProgress::default();
56    let parsed = read_with_fields(data, tree, ctx, Some(&mut progress))?;
57    Ok((parsed, progress))
58}
59
60pub(crate) fn read_with_fields(
61    data: &Bytes,
62    tree: &Arc<Tree>,
63    ctx: &ReadCtx<'_>,
64    progress: Option<&mut super::FieldProgress>,
65) -> Result<Parsed, ReadError> {
66    read_resolved(data, tree, ctx, progress, None)
67}
68
69/// Caller-supplied reference lookup, invoked only for a selected data field.
70/// The resolver returns the selected tree, or `None` for a disabled tree.
71type ReferenceResolver<'a> =
72    dyn FnMut(&Value, &Value, &Value, u64) -> Result<Option<Arc<Tree>>, ReadError> + 'a;
73
74/// Read with a lazy reference resolver, retaining ordinary object-field progress.
75pub fn read_resolved(
76    data: &Bytes,
77    tree: &Arc<Tree>,
78    ctx: &ReadCtx<'_>,
79    progress: Option<&mut super::FieldProgress>,
80    resolver: Option<&mut ReferenceResolver<'_>>,
81) -> Result<Parsed, ReadError> {
82    let work = Work::start(ctx.options.limits, ctx.meter)?;
83    let builder =
84        ValueBuilder::new(ctx.meter, tree.list().clone()).map_err(|e| charge_error(0, e))?;
85    let trees = Trees::new(&builder, tree)?;
86    let mut r = Reader {
87        data,
88        bytes: data.as_ref(),
89        pos: 0,
90        big: ctx.endian == Endian::Big,
91        floats: ctx.options.floats,
92        ref_types: ctx.ref_types,
93        refs: RefIndex::new(ctx.ref_types),
94        builder,
95        trees,
96        work,
97        has_registry: false,
98        method: "read_length",
99        progress,
100        resolver,
101    };
102    let value = r.value(tree, 0, tree.root());
103    let at = r.at();
104    let ended = r.work.finish(at);
105    let value = value?;
106    ended?;
107    let built = value.into_built(&r.builder, at)?;
108    // UnityPy TypeTreeHelper.cpp:1045: `bytes_read = reader.ptr - reader.start`.
109    let bytes_read = i64::try_from(r.pos).unwrap_or(i64::MAX);
110    let Reader { builder, .. } = r;
111    Ok(builder.finish(built, bytes_read))
112}
113
114/// UnityPyBoost's `ReaderT` (`TypeTreeHelper.cpp:13-18`) and its config
115/// (`:20-26`), with the reader's own bounds on work.
116struct Reader<'a, 'c, 'p, 'r, 's> {
117    data: &'a Bytes,
118    bytes: &'a [u8],
119    /// `ptr - start`: may pass the end after an alignment (R3).
120    pos: usize,
121    big: bool,
122    floats: FloatMode,
123    ref_types: RefTypes<'c>,
124    /// The ref types' search, one per read ([`RefIndex`]).
125    refs: RefIndex<'c>,
126    builder: ValueBuilder,
127    trees: Trees,
128    work: Work<'c>,
129    /// `config->has_registry` (R13).
130    has_registry: bool,
131    method: &'static str,
132    progress: Option<&'p mut super::FieldProgress>,
133    resolver: Option<&'r mut ReferenceResolver<'s>>,
134}
135
136/// A fixed-width number from its bytes in the file's order.
137macro_rules! num {
138    ($big:expr, $t:ty, $b:expr) => {
139        if $big {
140            <$t>::from_be_bytes($b)
141        } else {
142            <$t>::from_le_bytes($b)
143        }
144    };
145}
146
147impl Reader<'_, '_, '_, '_, '_> {
148    fn at(&self) -> u64 {
149        u64::try_from(self.pos).unwrap_or(u64::MAX)
150    }
151
152    fn fail(&self, kind: ReadErrorKind, detail: ReadDetail) -> ReadError {
153        ReadError {
154            kind,
155            at: self.at(),
156            detail,
157        }
158    }
159
160    /// A read past the end (`EOFError`, or a `ValueError` "... out of
161    /// bounds"): kind `out_of_bounds` either way (`dump_records.error_kind`).
162    fn eof(&self, need: usize, exception: &'static str) -> ReadError {
163        self.fail(
164            ReadErrorKind::OutOfBounds,
165            ReadDetail::BoostEof {
166                method: self.method,
167                need: u64::try_from(need).unwrap_or(u64::MAX),
168                exception,
169            },
170        )
171    }
172
173    /// R2: `ptr + n > end` fails. The end of the `n` bytes. A check of `n =
174    /// 0` never fails: every one follows a 4-byte length that passed its own
175    /// check, so the position is within the bytes (an empty run or string
176    /// after an alignment past the end fails at its length, as UnityPyBoost's
177    /// `_read_length` and then `ptr + n > end` do, `TypeTreeHelper.cpp:269`,
178    /// `:296`; review round 16).
179    fn bound(&self, n: usize, exception: &'static str) -> Result<usize, ReadError> {
180        match self.pos.checked_add(n) {
181            Some(end) if end <= self.bytes.len() => Ok(end),
182            _ => Err(self.eof(n, exception)),
183        }
184    }
185
186    fn fixed<const N: usize>(&mut self) -> Result<[u8; N], ReadError> {
187        let exception = if N == 1 { "ValueError" } else { "EOFError" };
188        let end = self.bound(N, exception)?;
189        let b = self
190            .bytes
191            .get(self.pos..end)
192            .and_then(|s| <[u8; N]>::try_from(s).ok())
193            .ok_or_else(|| self.eof(N, exception))?;
194        self.pos = end;
195        Ok(b)
196    }
197
198    /// R3: `align4` from the object's start, no bounds check
199    /// (UnityPy TypeTreeHelper.cpp:67-72).
200    fn align4(&mut self) {
201        self.pos = self.pos.checked_add(3).map_or(usize::MAX & !3, |p| p & !3);
202    }
203
204    /// `_read_length` (UnityPy TypeTreeHelper.cpp:266-286): bounds, then a
205    /// negative length fails before the cursor moves.
206    fn length(&mut self) -> Result<usize, ReadError> {
207        self.method = "read_length";
208        let end = self.bound(4, "EOFError")?;
209        let b = self
210            .bytes
211            .get(self.pos..end)
212            .and_then(|s| <[u8; 4]>::try_from(s).ok())
213            .ok_or_else(|| self.eof(4, "EOFError"))?;
214        let n = num!(self.big, i32, b);
215        let Ok(len) = usize::try_from(n) else {
216            return Err(self.fail(
217                ReadErrorKind::NegativeLength,
218                ReadDetail::NegativeLength(i64::from(n)),
219            ));
220        };
221        self.pos = end;
222        Ok(len)
223    }
224
225    /// R4, R5: one scalar (`read_u8`, `read_s8`, `read_bool`, `read_num`,
226    /// UnityPy TypeTreeHelper.cpp:74-204).
227    fn prim(&mut self, kind: Kind) -> Result<Value, ReadError> {
228        self.method = read_method(kind, false);
229        let big = self.big;
230        Ok(match kind {
231            Kind::U8 => int(i64::from(u8::from_le_bytes(self.fixed()?))),
232            Kind::S8 => int(i64::from(i8::from_le_bytes(self.fixed()?))),
233            // UnityPy TypeTreeHelper.cpp:81: any non-zero byte is true.
234            Kind::Bool => Value::Bool(u8::from_le_bytes(self.fixed()?) != 0),
235            Kind::U16 => int(i64::from(num!(big, u16, self.fixed()?))),
236            Kind::S16 => int(i64::from(num!(big, i16, self.fixed()?))),
237            Kind::U32 => int(i64::from(num!(big, u32, self.fixed()?))),
238            Kind::S32 => int(i64::from(num!(big, i32, self.fixed()?))),
239            Kind::U64 => uint(num!(big, u64, self.fixed()?)),
240            Kind::S64 => int(num!(big, i64, self.fixed()?)),
241            Kind::F32 => Value::F32(f32_bits(num!(big, u32, self.fixed()?), self.floats)),
242            Kind::F64 => Value::F64(num!(big, u64, self.fixed()?)),
243            _ => {
244                return Err(self.fail(ReadErrorKind::Other, ReadDetail::Python("not a primitive")));
245            }
246        })
247    }
248
249    fn tuple2(&mut self, first: Out, second: Out) -> Result<Out, ReadError> {
250        let at = self.at();
251        let mut items = self.builder.vec();
252        items.reserve_exact(2).map_err(|e| charge_error(at, e))?;
253        first.push_to(&mut items).map_err(|e| charge_error(at, e))?;
254        second
255            .push_to(&mut items)
256            .map_err(|e| charge_error(at, e))?;
257        let built = self.builder.tuple(items).map_err(|e| charge_error(at, e))?;
258        Ok(Out::Built(built))
259    }
260
261    /// `read_num_array` and friends (UnityPy TypeTreeHelper.cpp:86-264):
262    /// the whole run's bounds first, then every element.
263    #[inline(never)]
264    fn nums<const N: usize, T>(
265        &mut self,
266        count: usize,
267        conv: impl Fn([u8; N]) -> T,
268        wrap: fn(MeteredVec<T>) -> PrimRun,
269    ) -> Result<Out, ReadError> {
270        let exception = if N == 1 { "ValueError" } else { "EOFError" };
271        let total = count
272            .checked_mul(N)
273            .ok_or_else(|| self.eof(usize::MAX, exception))?;
274        let end = self.bound(total, exception)?;
275        let at = self.at();
276        self.work.run(as_u64(total), at)?;
277        let mut items: MeteredVec<T> = self.builder.vec();
278        // The bytes are there: the run's memory is that of its bytes.
279        items
280            .reserve_exact(count)
281            .map_err(|e| charge_error(at, e))?;
282        let (chunks, _) = self
283            .bytes
284            .get(self.pos..end)
285            .unwrap_or_default()
286            .as_chunks::<N>();
287        for b in chunks {
288            items.push(conv(*b)).map_err(|e| charge_error(at, e))?;
289        }
290        self.pos = end;
291        let built = self
292            .builder
293            .prims(wrap(items))
294            .map_err(|e| charge_error(at, e))?;
295        Ok(Out::Built(built))
296    }
297
298    /// `get_ref_type_node` (UnityPy TypeTreeHelper.cpp:585-681) on the dict
299    /// read so far, whose `type` entry is `ty`: `None` for an empty class
300    /// (the data is skipped), else the matched ref type's node. Every
301    /// failure is `ref_type`: the caller replaces the message with "Failed
302    /// to get ref type node" (`:763`).
303    fn ref_node(
304        &mut self,
305        ty: Option<&Value>,
306        object_type: bool,
307    ) -> Result<Option<RefNode>, ReadError> {
308        let ref_type = |d: ReadDetail| self.fail(ReadErrorKind::RefType, d);
309        if let RefTypes::NoFile | RefTypes::Absent = self.ref_types {
310            // `:587-591`, `:592-598`.
311            return Err(ref_type(ReadDetail::NoRefTypes {
312                reader: crate::value::ReadBy::Boost,
313                absent: matches!(self.ref_types, RefTypes::Absent),
314            }));
315        }
316        // `:600-606`: `type` read yet; `:611-635`: a dict with all three
317        // keys (any other object the reader makes has no such attributes).
318        let Some(Value::Dict(m)) = ty else {
319            return Err(ref_type(ReadDetail::RefTypeNotFound));
320        };
321        let at = self.at();
322        let mut field = |name: &[u8]| {
323            self.trees
324                .field(m, name, &mut self.work.open, object_type)
325                .map_err(|l| limit_refused(at, l))
326        };
327        let (Some(cls), Some(ns), Some(asm)) = (field(b"class")?, field(b"ns")?, field(b"asm")?)
328        else {
329            return Err(self.fail(ReadErrorKind::RefType, ReadDetail::RefTypeNotFound));
330        };
331        // `:637-644`: `PyUnicode_GET_LENGTH(cls) == 0` skips the data.
332        if py_size_field_is_zero(cls) {
333            return Ok(None);
334        }
335        if let Some(resolve) = &mut self.resolver {
336            return resolve(cls, ns, asm, at)
337                .map(|tree| Some(tree.map_or(RefNode::NoTree, RefNode::Tree)));
338        }
339        // `:646-673`: the first ref type whose three names compare equal.
340        let found = self
341            .refs
342            .find(self.builder.meter(), &mut self.work.open, cls, ns, asm)
343            .map_err(|e| match e {
344                FindError::Charge(e) => charge_error(at, e),
345                FindError::Work(l) => limit_refused(at, l),
346            })?;
347        match found {
348            Some(r) => Ok(Some(ref_tree(r, &self.work.limits, at)?)),
349            None => Err(self.fail(ReadErrorKind::RefType, ReadDetail::RefTypeNotFound)),
350        }
351    }
352}
353
354/// A `pair`'s two children (its shape checked them).
355fn two(t: &Tree, node: NodeId) -> (NodeId, NodeId) {
356    match t.list().children(node) {
357        [a, b, ..] => (*a, *b),
358        [a] => (*a, *a),
359        [] => (node, node),
360    }
361}
362
363fn as_u64(n: usize) -> u64 {
364    u64::try_from(n).unwrap_or(u64::MAX)
365}
366
367// TypeTreeHelper.cpp's typeid(T).name() uses the platform C++ ABI.
368fn read_method(kind: Kind, array: bool) -> &'static str {
369    macro_rules! name {
370        ($suffix:literal) => {
371            if array {
372                concat!("read_", $suffix, "_array")
373            } else {
374                concat!("read_", $suffix)
375            }
376        };
377    }
378    match kind {
379        Kind::Bool => name!("bool"),
380        Kind::U8 => name!("u8"),
381        Kind::S8 => name!("s8"),
382        Kind::U16 => name!("t"),
383        Kind::S16 => name!("s"),
384        Kind::U32 => name!("j"),
385        Kind::S32 => name!("i"),
386        Kind::U64 if cfg!(target_os = "macos") => name!("y"),
387        Kind::S64 if cfg!(target_os = "macos") => name!("x"),
388        Kind::U64 => name!("m"),
389        Kind::S64 => name!("l"),
390        Kind::F32 => name!("f"),
391        Kind::F64 => name!("d"),
392        _ => "read_length",
393    }
394}
395
396// After `num!`, which its steps use.
397#[path = "boost_states.rs"]
398mod states;
399#[path = "boost_steps.rs"]
400mod steps;