unityrs_core/stream.rs
1// Ported from UnityPy 1.25.2 (MIT): UnityPy/streams/EndianBinaryReader.py. See THIRD_PARTY_LICENSES.
2//! A bounded reader over a byte slice with the semantics of UnityPy's
3//! `EndianBinaryReader`: the memory reader, `EndianBinaryReader_Memoryview`
4//! (`streams/EndianBinaryReader.py:231-284`), or the stream reader,
5//! `EndianBinaryReader_Streamable` (`:287-324`), which UnityPy reads a file
6//! it loads from a path with ([`ReaderKind`]; `kind`'s module docs list
7//! what it reads that way and its rules).
8//!
9//! Container and metadata parsers read through it; the value walker has its
10//! own cursor (UnityPyBoost's bounds rule differs, plan section 3.10), which
11//! takes the same [`ReaderKind`]. No method panics: every read UnityPy
12//! refuses is an [`Error::OutOfBounds`], or the stream reader's
13//! [`StreamRefusal`] as an [`Error::Malformed`].
14//!
15//! **Positions are signed** (plan section 3.3). A Python `Position` is an
16//! unbounded integer that UnityPy moves with plain arithmetic, so on the
17//! memory reader it can go negative (a negative `node_count` in
18//! `parse_blob`, `file_size - metadata_size` below format 9, `Length -
19//! compressedSize` for blocks-info at the end, a negative `TypelessData`
20//! length on the pure-Python path) or past the end, and the reads after it
21//! go on with Python's rules, which this module's helpers implement once
22//! and an oracle fixture pins (`tests/fixtures/scaffold/reader.json`, from
23//! `tools/fixtures/scaffold.py`):
24//! - [`py_read`]: `read(n)`, a Python slice (negative indexes count from the
25//! end; a reversed range is empty); the position moves by `n` whatever
26//! the slice held;
27//! - [`py_unpack_from`]: every fixed-width read of 2, 4 or 8 bytes is
28//! `struct.unpack_from(view, Position)` (`:340-343`): a negative offset
29//! counts from the end, and the read must fit;
30//! - one-byte reads (`read_u8`, `read_i8`, `read_bool`) are
31//! `unpack(fmt, read(1))` (`:93-97`, `:126-127`): the slice of [`py_read`] must hold
32//! exactly one byte, and the position has moved by 1 even when it raises
33//! (at `-1`, `view[-1:0]` is empty);
34//! - [`py_align`]: `align_stream`, Python's floor modulo (`-7` aligns to `-4`);
35//! - [`py_string_to_null`]: `re.search` clamps its start and end into the
36//! buffer, a hit sets the absolute position after the NUL, and a miss reads
37//! `max_length` bytes as a slice unless `pos + max_length >= len`.
38//!
39//! The stream reader's position is never negative and stops at the end; the
40//! same fixture pins its rules (its `stream_` cases), which [`ReaderKind`]
41//! implements.
42//!
43//! Owner: package C. The free functions and [`Reader::read_i32_array`] are
44//! the scaffold's (implemented).
45
46mod kind;
47
48use std::ops::Range;
49use std::sync::Arc;
50
51use crate::error::Error;
52use crate::limits::{Meter, MeteredVec};
53
54pub use kind::{ReaderKind, STREAM_READER, StreamRefusal};
55
56/// Byte order of a reader or a file.
57#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
58pub enum Endian {
59 /// `<`
60 Little,
61 /// `>`
62 Big,
63}
64
65/// `read_string_to_null`'s default `max_length` (`EndianBinaryReader.py:275`).
66/// Within the window the string runs to its NUL. With no NUL in the window it
67/// is cut at the window when more bytes follow, and raises otherwise.
68pub const STRING_TO_NULL_WINDOW: usize = 32_767;
69
70/// The memoryview reader's `read(size)` at `pos` over `len` bytes
71/// (`streams/EndianBinaryReader.py:249-256`), with Python's arithmetic: size
72/// 0 reads nothing and leaves the position; size -1 reads to the end; any
73/// other size is the slice `view[pos : pos + size]`, where a negative index
74/// counts from the end, indexes clamp to `0..=len` and a reversed range is
75/// empty. Returns the byte range and the new position, `pos + size` (`len`
76/// for -1), which may be negative or past the end, as a Python `Position` can
77/// be. A bundle entry (`File.py:78-81`), `parse_blob`'s node area and string
78/// buffer, and the pure-Python reader's `TypelessData` all read this way
79/// (plan section 3.6). Implemented by the scaffold.
80#[must_use]
81pub fn py_read(len: usize, pos: i128, size: i64) -> (Range<usize>, i128) {
82 if size == 0 {
83 return (0..0, pos);
84 }
85 let l = i128::try_from(len).unwrap_or(i128::MAX);
86 let size = if size == -1 {
87 l.saturating_sub(pos)
88 } else {
89 i128::from(size)
90 };
91 let stop = pos.saturating_add(size);
92 let index = |i: i128| -> usize {
93 let i = if i < 0 { i.saturating_add(l) } else { i };
94 usize::try_from(i.clamp(0, l)).unwrap_or(0)
95 };
96 let start = index(pos);
97 let end = index(stop).max(start);
98 (start..end, stop)
99}
100
101/// `struct.unpack_from(fmt, view, pos)` for a format of `n` bytes over `len`
102/// bytes (`CPython`'s `s_unpack_from`): the start index of the bytes it reads,
103/// or `None` where it raises `struct.error`. A negative `pos` counts from the
104/// end and must leave the whole read before the end (`pos + n <= 0`) and
105/// inside the buffer (`pos + len >= 0`). Every fixed-width read of 2, 4 or 8
106/// bytes UnityPy's memoryview reader makes through its own methods
107/// (`reader.read_int()`) takes this path, then moves the position by `n`
108/// (only on success). The pure-Python typetree reader's primitive nodes do
109/// not: they read through the base class's `unpack(fmt, read(n))`
110/// (`walk::python`, plan 3.10). Implemented by the scaffold.
111#[must_use]
112pub fn py_unpack_from(len: usize, pos: i128, n: usize) -> Option<usize> {
113 let l = i128::try_from(len).ok()?;
114 let n = i128::try_from(n).ok()?;
115 let mut offset = pos;
116 if offset < 0 {
117 if offset.saturating_add(n) > 0 || offset.saturating_add(l) < 0 {
118 return None;
119 }
120 offset = offset.saturating_add(l);
121 }
122 if l.saturating_sub(offset) < n {
123 return None;
124 }
125 usize::try_from(offset).ok()
126}
127
128/// `align_stream(n)` (`streams/EndianBinaryReader.py:155-156`):
129/// `pos + (n - pos % n) % n` with Python's floor modulo, so a negative
130/// position aligns towards zero (`-7` to `-4` for `n = 4`). `n` 0 leaves the
131/// position (Python would raise; no caller passes 0). Implemented by the scaffold.
132#[must_use]
133pub fn py_align(pos: i128, n: u32) -> i128 {
134 let n = i128::from(n);
135 if n == 0 {
136 return pos;
137 }
138 pos.saturating_add((n - pos.rem_euclid(n)) % n)
139}
140
141/// `read_string_to_null(max_length)` of the memoryview reader
142/// (`streams/EndianBinaryReader.py:275-284`) at `pos` over `data`: the
143/// string's byte range and the new position, or `None` where it raises
144/// ("String not terminated"). `re.search(view, pos, pos + max_length)` clamps
145/// both bounds into `0..=len` (`py_string_window`), so a negative start
146/// searches from 0; a hit returns the bytes up to the first NUL in the window
147/// and sets the position after that NUL (an absolute index). With no NUL in
148/// the window it raises when `pos + max_length >= len`, and otherwise returns
149/// `read(max_length)`, a slice from `pos` that may hold a NUL or nothing at
150/// all (`py_string_to_null_found`, which a caller that indexed the buffer's
151/// NULs answers with). Implemented by the scaffold.
152#[must_use]
153pub fn py_string_to_null(
154 data: &[u8],
155 pos: i128,
156 max_length: usize,
157) -> Option<(Range<usize>, i128)> {
158 let window = py_string_window(data.len(), pos, max_length);
159 let nul = data
160 .get(window.clone())
161 .and_then(|w| w.iter().position(|b| *b == 0))
162 .map(|k| window.start + k);
163 py_string_to_null_found(data.len(), pos, max_length, nul)
164}
165
166/// The bytes [`py_string_to_null`] searches for its NUL at `pos` over `len`
167/// bytes: `re.search`'s window `pos..pos + max_length`, each bound clamped
168/// into `0..=len`, empty where the end falls before the start.
169#[must_use]
170pub(crate) fn py_string_window(len: usize, pos: i128, max_length: usize) -> Range<usize> {
171 let l = i128::try_from(len).unwrap_or(i128::MAX);
172 let max = i128::try_from(max_length).unwrap_or(i128::MAX);
173 let clamp = |i: i128| usize::try_from(i.clamp(0, l)).unwrap_or(0);
174 let start = clamp(pos);
175 start..clamp(pos.saturating_add(max)).max(start)
176}
177
178/// [`py_string_to_null`]'s answer once its search is done: `nul` is the
179/// first NUL in [`py_string_window`]'s window, as an index of the whole
180/// buffer, or `None` where the window holds none. A caller that knows where
181/// the NULs are (a typetree blob's string buffer, indexed once) answers
182/// every offset without searching it again.
183#[must_use]
184pub(crate) fn py_string_to_null_found(
185 len: usize,
186 pos: i128,
187 max_length: usize,
188 nul: Option<usize>,
189) -> Option<(Range<usize>, i128)> {
190 let l = i128::try_from(len).ok()?;
191 let max = i128::try_from(max_length).ok()?;
192 if let Some(nul) = nul {
193 let start = py_string_window(len, pos, max_length).start;
194 return Some((start..nul, i128::try_from(nul).ok()? + 1));
195 }
196 if pos.saturating_add(max) >= l {
197 return None;
198 }
199 Some(py_read(len, pos, i64::try_from(max_length).ok()?))
200}
201
202/// What `read(N)` returns where UnityPy keeps the bytes as they are (a
203/// GUID, a hash): the [`py_read`] slice, inline. It holds `N` bytes, or
204/// fewer where the slice is short: none at a position in `-N..0` (the
205/// slice `view[p:p+N]` runs from the end back to the start, so it is
206/// empty, though the position moves to `p + N`), the rest at the end.
207#[derive(Clone, Copy, PartialEq, Eq, Hash)]
208pub struct ShortArray<const N: usize> {
209 bytes: [u8; N],
210 len: usize,
211}
212
213const _: () = crate::send_sync::<ShortArray<16>>();
214
215impl<const N: usize> ShortArray<N> {
216 /// The first `N` bytes of `got` (all of it, when shorter).
217 #[must_use]
218 pub fn from_slice(got: &[u8]) -> Self {
219 let len = got.len().min(N);
220 let mut bytes = [0u8; N];
221 if let (Some(to), Some(from)) = (bytes.get_mut(..len), got.get(..len)) {
222 to.copy_from_slice(from);
223 }
224 Self { bytes, len }
225 }
226
227 /// The bytes read.
228 #[must_use]
229 pub fn as_slice(&self) -> &[u8] {
230 self.bytes.get(..self.len).unwrap_or_default()
231 }
232}
233
234impl<const N: usize> From<[u8; N]> for ShortArray<N> {
235 fn from(bytes: [u8; N]) -> Self {
236 Self { bytes, len: N }
237 }
238}
239
240impl<const N: usize> std::ops::Deref for ShortArray<N> {
241 type Target = [u8];
242
243 fn deref(&self) -> &[u8] {
244 self.as_slice()
245 }
246}
247
248impl<const N: usize> std::fmt::Debug for ShortArray<N> {
249 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
250 self.as_slice().fmt(f)
251 }
252}
253
254/// A cursor over `data`, read by the rules of one of UnityPy's readers
255/// ([`ReaderKind`]). Positions are absolute within `data` and signed, as a
256/// Python `Position` (module docs): on the memory reader every read follows
257/// the helper of its Python primitive at whatever position it is, negative
258/// or past the end; the stream reader's position is never negative.
259#[derive(Clone, Debug)]
260pub struct Reader<'a> {
261 data: &'a [u8],
262 pos: i128,
263 endian: Endian,
264 kind: ReaderKind,
265}
266
267impl<'a> Reader<'a> {
268 /// A memory reader at position 0 (what UnityPy reads bytes with).
269 #[must_use]
270 pub fn new(data: &'a [u8], endian: Endian) -> Self {
271 Self::with_kind(data, endian, ReaderKind::Memory)
272 }
273
274 /// A reader of `kind` at position 0.
275 #[must_use]
276 pub fn with_kind(data: &'a [u8], endian: Endian, kind: ReaderKind) -> Self {
277 Self {
278 data,
279 pos: 0,
280 endian,
281 kind,
282 }
283 }
284
285 /// The whole slice.
286 #[must_use]
287 pub fn data(&self) -> &'a [u8] {
288 self.data
289 }
290
291 /// Which reader's rules it reads by.
292 #[must_use]
293 pub fn kind(&self) -> ReaderKind {
294 self.kind
295 }
296
297 /// The position, as Python holds it.
298 #[must_use]
299 pub fn position(&self) -> i128 {
300 self.pos
301 }
302
303 /// An assignment to `reader.Position`: the memory reader takes any
304 /// position, negative or past the end; the stream reader refuses a
305 /// negative one or one at or above 2^63 ([`ReaderKind::seek`]), and
306 /// stays where it was.
307 pub fn set_position(&mut self, pos: i128) -> Result<(), Error> {
308 self.pos = self.kind.seek(pos)?;
309 Ok(())
310 }
311
312 /// Where a read the caller made itself, by this reader's rules, leaves
313 /// the position (`typetree::parse::string_to_null`): no assignment, so
314 /// nothing to refuse.
315 pub(crate) fn advance_to(&mut self, pos: i128) {
316 self.pos = pos;
317 }
318
319 /// The byte order of multi-byte reads.
320 #[must_use]
321 pub fn endian(&self) -> Endian {
322 self.endian
323 }
324
325 /// Changes the byte order (a `SerializedFile` header switches it).
326 pub fn set_endian(&mut self, endian: Endian) {
327 self.endian = endian;
328 }
329
330 /// The bytes `read(-1)` would return from here: what a table's growth may
331 /// count on (plan section 3.3). The same on both readers.
332 #[must_use]
333 pub fn remaining(&self) -> usize {
334 py_read(self.data.len(), self.pos, -1).0.len()
335 }
336
337 /// `align_stream(n)`: [`py_align`], without a bounds check, assigned
338 /// to the position: the memory reader takes any result; the stream
339 /// reader's position is never negative, so the arithmetic is the same,
340 /// and it refuses a result at or above 2^63 as its `seek` does
341 /// ([`ReaderKind::align`]), staying where it was.
342 pub fn align(&mut self, n: u32) -> Result<(), Error> {
343 // UnityPy streams/EndianBinaryReader.py:155-156
344 self.pos = self.kind.align(self.pos, n)?;
345 Ok(())
346 }
347
348 /// The bytes after the position, as [`Error::OutOfBounds`] reports them.
349 fn have(&self) -> u64 {
350 u64::try_from(self.remaining()).unwrap_or(u64::MAX)
351 }
352
353 fn out_of_bounds(&self, what: &'static str, pos: i128, need: usize) -> Error {
354 Error::OutOfBounds {
355 what,
356 pos,
357 need: u64::try_from(need).unwrap_or(u64::MAX),
358 have: self.have(),
359 reader: self.kind,
360 length: self.data.len(),
361 }
362 }
363
364 /// `read(n)`, the range of `data` it returns: the memory reader's
365 /// [`py_read`] slice, short or empty at the ends (`read_bytes` on a
366 /// truncated block, `File.py:79`), the position moved by `n`; or the
367 /// stream reader's, which refuses an `n` below -1 and stops at the end
368 /// ([`ReaderKind::read`]).
369 pub fn read_range(&mut self, n: i64) -> Result<Range<usize>, Error> {
370 // UnityPy streams/EndianBinaryReader.py:249-256, :295
371 let (range, pos) = self.kind.read(self.data.len(), self.pos, n)?;
372 self.pos = pos;
373 Ok(range)
374 }
375
376 /// `read(n)` as it is: [`Self::read_range`]'s bytes.
377 pub fn read(&mut self, n: i64) -> Result<&'a [u8], Error> {
378 let range = self.read_range(n)?;
379 Ok(self.data.get(range).unwrap_or_default())
380 }
381
382 /// `n` bytes where UnityPy's caller unpacks them whole (`read(n)`, then
383 /// `struct.unpack`): what `read(n)` returns must hold `n` bytes, else
384 /// `OutOfBounds`; the position moves as `read(n)` moves it either way.
385 pub fn read_bytes(&mut self, n: usize) -> Result<&'a [u8], Error> {
386 let pos = self.pos;
387 let got = self.read(i64::try_from(n).unwrap_or(i64::MAX))?;
388 if got.len() == n {
389 Ok(got)
390 } else {
391 Err(self.out_of_bounds("bytes", pos, n))
392 }
393 }
394
395 /// `read(n)` as it is for a size UnityPy's own code fixes (3, 16 or 32
396 /// bytes), which neither reader refuses: short or empty at the ends.
397 pub fn read_bytes_short(&mut self, n: usize) -> &'a [u8] {
398 self.read(i64::try_from(n).unwrap_or(i64::MAX))
399 .unwrap_or_default()
400 }
401
402 /// `read_string_to_null` with the 32,767-byte window, by the reader's
403 /// rule ([`py_string_to_null`] or the stream reader's loop,
404 /// [`ReaderKind::string_to_null`]).
405 pub fn read_string_to_null(&mut self) -> Result<&'a [u8], Error> {
406 // UnityPy streams/EndianBinaryReader.py:136-144, :275-284
407 let pos = self.pos;
408 match self
409 .kind
410 .string_to_null(self.data, pos, STRING_TO_NULL_WINDOW)
411 {
412 Some((range, new)) => {
413 self.pos = new;
414 Ok(self.data.get(range).unwrap_or_default())
415 }
416 None => Err(self.out_of_bounds("string to null", pos, 1)),
417 }
418 }
419
420 /// The error [`Self::read_string_to_null`] raises at the position, for
421 /// a caller that searched the window itself and found no NUL with no
422 /// room left (`typetree::parse::string_to_null`).
423 pub(crate) fn string_to_null_error(&self) -> Error {
424 self.out_of_bounds("string to null", self.pos, 1)
425 }
426
427 /// One byte for `unpack(fmt, read(1))` (`:93-97`): the position moves as
428 /// `read(1)` moves it even when it returns nothing.
429 fn one_byte(&mut self, what: &'static str) -> Result<u8, Error> {
430 let pos = self.pos;
431 match self.read_bytes_short(1) {
432 [b] => Ok(*b),
433 _ => Err(self.out_of_bounds(what, pos, 1)),
434 }
435 }
436
437 /// One byte as a bool (non-zero is true): `unpack("?", read(1))`.
438 pub fn read_bool(&mut self) -> Result<bool, Error> {
439 // UnityPy streams/EndianBinaryReader.py:126-127
440 self.one_byte("bool").map(|b| b != 0)
441 }
442
443 /// `u8`: `unpack("B", read(1))`.
444 pub fn read_u8(&mut self) -> Result<u8, Error> {
445 // UnityPy streams/EndianBinaryReader.py:96-97
446 self.one_byte("u8")
447 }
448
449 /// `i8`: `unpack("b", read(1))`.
450 pub fn read_i8(&mut self) -> Result<i8, Error> {
451 // UnityPy streams/EndianBinaryReader.py:93-94
452 self.one_byte("i8").map(|b| i8::from_le_bytes([b]))
453 }
454
455 /// `N` bytes by the reader's own fixed-width read ([`ReaderKind::unpack`]):
456 /// `struct.unpack_from(view, Position)` (`:340-343`) on the memory
457 /// reader, whose position moves by `N` only on success;
458 /// `struct.unpack(stream.read(N))` (`:345-346`) on the stream reader,
459 /// whose position moves by what it read either way.
460 fn fixed<const N: usize>(&mut self, what: &'static str) -> Result<[u8; N], Error> {
461 let pos = self.pos;
462 let (at, next) = self.kind.unpack(self.data.len(), pos, N);
463 let Some(at) = at else {
464 let e = self.out_of_bounds(what, pos, N);
465 self.pos = next;
466 return Err(e);
467 };
468 let mut b = [0u8; N];
469 if let Some(src) = self.data.get(at..at.saturating_add(N)) {
470 b.copy_from_slice(src);
471 }
472 self.pos = next;
473 if self.endian == Endian::Big {
474 b.reverse();
475 }
476 // Little-endian from here on.
477 Ok(b)
478 }
479
480 /// `u16` in the reader's byte order: [`ReaderKind::unpack`].
481 pub fn read_u16(&mut self) -> Result<u16, Error> {
482 self.fixed("u16").map(u16::from_le_bytes)
483 }
484
485 /// `i16` in the reader's byte order: [`ReaderKind::unpack`].
486 pub fn read_i16(&mut self) -> Result<i16, Error> {
487 self.fixed("i16").map(i16::from_le_bytes)
488 }
489
490 /// `u32` in the reader's byte order: [`ReaderKind::unpack`].
491 pub fn read_u32(&mut self) -> Result<u32, Error> {
492 self.fixed("u32").map(u32::from_le_bytes)
493 }
494
495 /// `i32` in the reader's byte order: [`ReaderKind::unpack`].
496 pub fn read_i32(&mut self) -> Result<i32, Error> {
497 self.fixed("i32").map(i32::from_le_bytes)
498 }
499
500 /// `u64` in the reader's byte order: [`ReaderKind::unpack`].
501 pub fn read_u64(&mut self) -> Result<u64, Error> {
502 self.fixed("u64").map(u64::from_le_bytes)
503 }
504
505 /// `i64` in the reader's byte order: [`ReaderKind::unpack`].
506 pub fn read_i64(&mut self) -> Result<i64, Error> {
507 self.fixed("i64").map(i64::from_le_bytes)
508 }
509
510 /// `read(N)` kept as it is ([`ShortArray`]): a GUID or a hash, which
511 /// UnityPy stores without checking its length, so a short read (on the
512 /// memory reader at a position in `-N..0`; at the end on either) is no
513 /// error; the position moves as `read(N)` moves it.
514 pub fn read_short_array<const N: usize>(&mut self) -> ShortArray<N> {
515 ShortArray::from_slice(self.read_bytes_short(N))
516 }
517
518 /// A fixed-size byte array: `read(N)`, which must hold `N` bytes where
519 /// UnityPy's caller needs them all (it unpacks them); where it keeps
520 /// them as they are, [`Self::read_short_array`].
521 pub fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error> {
522 let got = self.read_bytes(N)?;
523 let mut b = [0u8; N];
524 b.copy_from_slice(got);
525 Ok(b)
526 }
527
528 /// `read_int_array` (`EndianBinaryReader.py:182`, `read_array_struct` at
529 /// `:164-168` and `:258-264`): an `i32` count read as the reader's own
530 /// `read_int` ([`ReaderKind::unpack`]), then the array: on the memory
531 /// reader `struct.unpack_from` of that many `i32` at the new position (a
532 /// negative one counts from the end), the position moving by
533 /// `4 * count`; on the stream reader `struct.unpack(read(4 * count))`,
534 /// which moves it by what it read, even when that is short. A negative
535 /// count raises (`Struct("<-1i")` is a bad format) with the position
536 /// after the count, as does an array the bytes do not hold (the stream
537 /// reader's has moved). The array is a vector on `meter`, the input's,
538 /// charged after the bytes are checked and before it is allocated, so a
539 /// count allocates nothing the bytes do not back and the array counts
540 /// against its input while it is kept (round 5: this returned a plain
541 /// `Vec`, the one input-sized allocation a parser made uncharged); a
542 /// refused charge is the meter's or the budget's error, with the
543 /// position after the count. Implemented by the scaffold; the cases are
544 /// recorded from UnityPy 1.25.2 (`read_i32_array_reads_as_unitypy_and_charges_the_meter`).
545 pub fn read_i32_array(&mut self, meter: &Arc<Meter>) -> Result<MeteredVec<i32>, Error> {
546 const WHAT: &str = "int array";
547 let len = self.data.len();
548 let have = self.have();
549 let (at, next) = self.kind.unpack(len, self.pos, 4);
550 let Some(at) = at else {
551 let e = Error::OutOfBounds {
552 what: WHAT,
553 pos: self.pos,
554 need: 4,
555 have,
556 reader: self.kind,
557 length: self.data.len(),
558 };
559 self.pos = next;
560 return Err(e);
561 };
562 let count = self.i32_at(at);
563 self.pos = next;
564 let Ok(n) = usize::try_from(count) else {
565 return Err(Error::Malformed {
566 what: WHAT,
567 detail: format!("negative count {count}").into(),
568 });
569 };
570 let (at, next) = n
571 .checked_mul(4)
572 .map_or((None, self.pos), |b| self.kind.unpack(len, self.pos, b));
573 let Some(at) = at else {
574 let e = Error::OutOfBounds {
575 what: WHAT,
576 pos: self.pos,
577 need: u64::try_from(n).unwrap_or(u64::MAX).saturating_mul(4),
578 have: self.have(),
579 reader: self.kind,
580 length: self.data.len(),
581 };
582 self.pos = next;
583 return Err(e);
584 };
585 let mut out = MeteredVec::with_capacity(meter, n)?;
586 for i in 0..n {
587 out.push(self.i32_at(at + 4 * i))?;
588 }
589 self.pos = next;
590 Ok(out)
591 }
592
593 /// The `i32` at `at`, which [`ReaderKind::unpack`] checked, in the
594 /// reader's byte order.
595 fn i32_at(&self, at: usize) -> i32 {
596 let mut b = [0u8; 4];
597 if let Some(src) = self.data.get(at..at + 4) {
598 b.copy_from_slice(src);
599 }
600 match self.endian {
601 Endian::Little => i32::from_le_bytes(b),
602 Endian::Big => i32::from_be_bytes(b),
603 }
604 }
605}
606
607#[cfg(test)]
608mod tests {
609 use super::{Endian, Reader, py_read};
610 use crate::budget::{Reservation, Unbounded};
611 use crate::error::Error;
612 use crate::error::LimitKind;
613 use crate::limits::{Meter, heap_cost};
614
615 #[test]
616 fn read_i32_array_reads_as_unitypy_and_charges_the_meter() {
617 // Recorded from UnityPy 1.25.2's memoryview reader (`read_int_array`
618 // at a set `Position`): (bytes, endian, position) -> values and the
619 // new position, or the error and the position after it.
620 let le = |v: &[i32]| v.iter().flat_map(|x| x.to_le_bytes()).collect::<Vec<u8>>();
621 let be = |v: &[i32]| v.iter().flat_map(|x| x.to_be_bytes()).collect::<Vec<u8>>();
622 let m = Meter::unlimited();
623 let ok = |data: &[u8], endian, pos: i128| {
624 let mut r = Reader::new(data, endian);
625 r.set_position(pos).unwrap();
626 let v = r.read_i32_array(&m).unwrap();
627 (v.as_slice().to_vec(), r.position(), v.charge().bytes())
628 };
629 assert_eq!(
630 ok(&le(&[3, 1, -2, 3]), Endian::Little, 0),
631 (vec![1, -2, 3], 16, heap_cost(12))
632 );
633 assert_eq!(
634 ok(&be(&[3, 1, -2, 3]), Endian::Big, 0),
635 (vec![1, -2, 3], 16, heap_cost(12))
636 );
637 // A negative position counts from the end, for the count and the
638 // array alike.
639 assert_eq!(
640 ok(&le(&[1, 7, 9]), Endian::Little, -12),
641 (vec![7], -4, heap_cost(4))
642 );
643 assert_eq!(ok(&le(&[0]), Endian::Little, 0), (vec![], 4, 0));
644
645 let err = |data: &[u8], limit: u64| {
646 let m = Meter::new(limit, std::sync::Arc::new(Unbounded), Reservation::Input);
647 let mut r = Reader::new(data, Endian::Little);
648 let e = r.read_i32_array(&m).unwrap_err();
649 (e, r.position(), m.used())
650 };
651 // UnityPy: `bad char in struct format`, Position 4.
652 let (e, pos, used) = err(&le(&[-1, 5]), u64::MAX);
653 assert!(matches!(e, Error::Malformed { .. }), "{e:?}");
654 assert_eq!((pos, used), (4, 0));
655 // A huge count over 4 bytes: refused by the bytes, nothing charged.
656 let (e, pos, used) = err(&le(&[i32::MAX, 5]), u64::MAX);
657 assert!(
658 matches!(
659 e,
660 Error::OutOfBounds {
661 need: 8_589_934_588,
662 ..
663 }
664 ),
665 "{e:?}"
666 );
667 assert_eq!((pos, used), (4, 0));
668 let (e, pos, _) = err(&[1, 0], u64::MAX);
669 assert!(matches!(e, Error::OutOfBounds { need: 4, .. }), "{e:?}");
670 assert_eq!(pos, 0);
671 // An array the bytes hold but the meter does not: refused before it
672 // is allocated.
673 let (e, pos, used) = err(&le(&[64; 65]), 100);
674 assert!(
675 matches!(&e, Error::Limit(l) if l.kind() == LimitKind::InputMemory),
676 "{e:?}"
677 );
678 assert_eq!((pos, used), (4, 0));
679 }
680
681 #[test]
682 fn py_read_is_a_python_slice() {
683 // Recorded from UnityPy 1.25.2's memoryview reader over bytes(range(10)):
684 // (position, size) -> (bytes read, new position).
685 let cases: &[(i128, i64, std::ops::Range<usize>, i128)] = &[
686 (0, 4, 0..4, 4),
687 (8, 4, 8..10, 12),
688 (12, 4, 10..10, 16),
689 (3, 0, 0..0, 3),
690 (3, -1, 3..10, 10),
691 (-3, 2, 7..9, -1),
692 (-3, 5, 7..7, 2),
693 (5, -3, 5..5, 2),
694 (2, -5, 2..7, -3),
695 (-20, 5, 0..0, -15),
696 (-1, -1, 9..10, 10),
697 // Past the end, size -1: `size = Length - Position` is -2, so the
698 // position comes back to the end (UnityPy: `read(-1)` at 12 of 10
699 // leaves Position 10).
700 (12, -1, 10..10, 10),
701 (15, -1, 10..10, 10),
702 (i128::from(i64::MIN), i64::MAX, 0..9, -1),
703 ];
704 for (pos, size, range, new_pos) in cases {
705 let (r, p) = py_read(10, *pos, *size);
706 assert_eq!(r.len(), range.len(), "({pos}, {size})");
707 if !range.is_empty() {
708 assert_eq!(r, *range, "({pos}, {size})");
709 }
710 assert_eq!(p, *new_pos, "({pos}, {size})");
711 }
712 }
713}