Skip to main content

unityrs_testkit/
writer.rs

1//! An endian-aware byte writer, the builders' only primitive.
2//!
3//! **Fields.** Every 4- and 8-byte integer a writer writes (`u32`, `i32`,
4//! `u64`, `i64`: each count, length, size and offset the builders write,
5//! and every other integer of those widths) is a *field*. While
6//! [`with_fields`] runs a build on the calling thread, the writers number
7//! the fields that build writes, in write order, report each one, and can
8//! write another value in place of any of them. G3b's mutator
9//! ([`crate::mutate`]) builds the gate's inputs this way, so a field is
10//! changed before anything that follows from it is computed: the bytes a
11//! codec compresses, the size of a block, the entry that holds a file.
12//! Outside [`with_fields`] a writer writes what it is given.
13
14use std::cell::RefCell;
15
16/// Little- or big-endian bytes, appended.
17#[derive(Clone, Debug, Default, PartialEq, Eq)]
18pub struct ByteWriter {
19    buf: Vec<u8>,
20    big_endian: bool,
21}
22
23impl ByteWriter {
24    /// A little-endian writer.
25    #[must_use]
26    pub fn le() -> Self {
27        Self::default()
28    }
29
30    /// A big-endian writer.
31    #[must_use]
32    pub fn be() -> Self {
33        Self {
34            buf: Vec::new(),
35            big_endian: true,
36        }
37    }
38
39    /// Switches byte order from here on.
40    pub fn set_big_endian(&mut self, big: bool) -> &mut Self {
41        self.big_endian = big;
42        self
43    }
44
45    /// Bytes written so far.
46    #[must_use]
47    pub fn len(&self) -> usize {
48        self.buf.len()
49    }
50
51    /// Whether nothing was written.
52    #[must_use]
53    pub fn is_empty(&self) -> bool {
54        self.buf.is_empty()
55    }
56
57    /// The bytes.
58    #[must_use]
59    pub fn into_inner(self) -> Vec<u8> {
60        self.buf
61    }
62
63    /// The bytes so far.
64    #[must_use]
65    pub fn as_slice(&self) -> &[u8] {
66        &self.buf
67    }
68
69    /// Raw bytes.
70    pub fn bytes(&mut self, b: &[u8]) -> &mut Self {
71        self.buf.extend_from_slice(b);
72        self
73    }
74
75    /// `b` and a NUL.
76    pub fn cstr(&mut self, b: &[u8]) -> &mut Self {
77        self.buf.extend_from_slice(b);
78        self.buf.push(0);
79        self
80    }
81
82    /// Zero bytes up to a multiple of `n` (UnityPy's `align_stream`, 4 by default).
83    pub fn align(&mut self, n: usize) -> &mut Self {
84        if n > 1 {
85            let pad = (n - self.buf.len() % n) % n;
86            self.buf.resize(self.buf.len() + pad, 0);
87        }
88        self
89    }
90
91    /// A `u8`.
92    pub fn u8(&mut self, v: u8) -> &mut Self {
93        self.buf.push(v);
94        self
95    }
96
97    /// A `bool` as one byte.
98    pub fn bool(&mut self, v: bool) -> &mut Self {
99        self.u8(u8::from(v))
100    }
101
102    /// An `i8`.
103    pub fn i8(&mut self, v: i8) -> &mut Self {
104        self.bytes(&v.to_le_bytes())
105    }
106}
107
108/// One field a build wrote (module docs).
109#[derive(Clone, Copy, Debug, PartialEq, Eq)]
110pub struct Field {
111    /// 4 or 8 bytes.
112    pub width: usize,
113    /// Written big-endian.
114    pub big_endian: bool,
115    /// The value it was given, as its `width` bytes read unsigned.
116    pub value: u64,
117}
118
119/// The state of [`with_fields`] on one thread.
120struct Hook {
121    /// Every field written so far.
122    written: Vec<Field>,
123    /// `(field number, value)` to write instead, sorted by number.
124    overrides: Vec<(usize, u64)>,
125}
126
127thread_local! {
128    static HOOK: RefCell<Option<Hook>> = const { RefCell::new(None) };
129}
130
131/// Runs `build` on this thread with each field it writes numbered from 0 in
132/// write order: field `n` is written as `v` where `overrides` holds
133/// `(n, v)` (its low `width` bytes), and as given otherwise. Returns what
134/// `build` returned and every field it wrote, with the value it was given.
135/// A nested call runs its build with a numbering of its own.
136pub fn with_fields<T>(overrides: &[(usize, u64)], build: impl FnOnce() -> T) -> (T, Vec<Field>) {
137    let mut sorted = overrides.to_vec();
138    sorted.sort_unstable();
139    let outer = HOOK.with(|h| {
140        h.borrow_mut().replace(Hook {
141            written: Vec::new(),
142            overrides: sorted,
143        })
144    });
145    let out = build();
146    let hook = HOOK.with(|h| std::mem::replace(&mut *h.borrow_mut(), outer));
147    (out, hook.map(|h| h.written).unwrap_or_default())
148}
149
150/// The value field `value` is written as under [`with_fields`], and records it.
151fn field(width: usize, big_endian: bool, value: u64) -> u64 {
152    HOOK.with(|h| {
153        let mut h = h.borrow_mut();
154        let Some(hook) = h.as_mut() else {
155            return value;
156        };
157        let n = hook.written.len();
158        hook.written.push(Field {
159            width,
160            big_endian,
161            value,
162        });
163        hook.overrides
164            .binary_search_by_key(&n, |o| o.0)
165            .ok()
166            .and_then(|i| hook.overrides.get(i))
167            .map_or(value, |o| o.1)
168    })
169}
170
171macro_rules! field {
172    ($($name:ident: $t:ty, $u:ty),*) => {
173        impl ByteWriter {
174            $(
175                #[doc = concat!("A `", stringify!($t), "` in the writer's byte order: a field (module docs).")]
176                pub fn $name(&mut self, v: $t) -> &mut Self {
177                    let width = std::mem::size_of::<$t>();
178                    let bits = <$u>::from_ne_bytes(v.to_ne_bytes());
179                    let w = field(width, self.big_endian, u64::from(bits));
180                    // The low `width` bytes of the value to write.
181                    let low = w.to_le_bytes();
182                    let mut b = [0u8; std::mem::size_of::<$t>()];
183                    b.copy_from_slice(&low[..width]);
184                    let v = <$u>::from_le_bytes(b);
185                    if self.big_endian {
186                        self.buf.extend_from_slice(&v.to_be_bytes());
187                    } else {
188                        self.buf.extend_from_slice(&v.to_le_bytes());
189                    }
190                    self
191                }
192            )*
193        }
194    };
195}
196
197field!(u32: u32, u32, i32: i32, u32, u64: u64, u64, i64: i64, u64);
198
199macro_rules! put {
200    ($($name:ident: $t:ty),*) => {
201        impl ByteWriter {
202            $(
203                #[doc = concat!("A `", stringify!($t), "` in the writer's byte order.")]
204                pub fn $name(&mut self, v: $t) -> &mut Self {
205                    if self.big_endian {
206                        self.buf.extend_from_slice(&v.to_be_bytes());
207                    } else {
208                        self.buf.extend_from_slice(&v.to_le_bytes());
209                    }
210                    self
211                }
212            )*
213        }
214    };
215}
216
217put!(u16: u16, i16: i16, f32: f32, f64: f64);
218
219#[cfg(test)]
220mod tests {
221    use super::{ByteWriter, Field, with_fields};
222
223    #[test]
224    fn fields_are_numbered_reported_and_overridden() {
225        let build = || {
226            let mut w = ByteWriter::le();
227            w.u32(5)
228                .u16(7)
229                .i64(-1)
230                .set_big_endian(true)
231                .i32(-2)
232                .f32(1.0);
233            w.into_inner()
234        };
235        let (plain, fields) = with_fields(&[], build);
236        assert_eq!(plain, build(), "no override, no change");
237        assert_eq!(
238            fields,
239            [
240                Field {
241                    width: 4,
242                    big_endian: false,
243                    value: 5
244                },
245                Field {
246                    width: 8,
247                    big_endian: false,
248                    value: u64::MAX
249                },
250                Field {
251                    width: 4,
252                    big_endian: true,
253                    value: 0xFFFF_FFFE
254                },
255            ]
256        );
257        // The second and third fields replaced; the u16 and the f32 are no fields.
258        let (b, _) = with_fields(&[(2, 0x0102_0304), (1, 9)], build);
259        let mut want = vec![5, 0, 0, 0, 7, 0, 9, 0, 0, 0, 0, 0, 0, 0, 1, 2, 3, 4];
260        want.extend_from_slice(&1.0f32.to_be_bytes());
261        assert_eq!(b, want);
262        // A value wider than its field keeps its low bytes; outside the hook
263        // nothing is recorded or replaced.
264        let (b, _) = with_fields(&[(0, 0x1_0000_0006)], build);
265        assert_eq!(&b[..4], &[6, 0, 0, 0]);
266        assert_eq!(build(), plain);
267    }
268
269    #[test]
270    fn a_nested_build_numbers_its_own_fields() {
271        let (outer, fields) = with_fields(&[(1, 8)], || {
272            let mut w = ByteWriter::le();
273            w.u32(1);
274            let (inner, inner_fields) = with_fields(&[(0, 4)], || {
275                let mut v = ByteWriter::le();
276                v.u32(2);
277                v.into_inner()
278            });
279            assert_eq!(inner, [4, 0, 0, 0]);
280            assert_eq!(inner_fields.len(), 1);
281            w.u32(3);
282            w.into_inner()
283        });
284        assert_eq!(outer, [1, 0, 0, 0, 8, 0, 0, 0]);
285        assert_eq!(fields.len(), 2);
286    }
287
288    #[test]
289    fn order_and_align() {
290        let mut w = ByteWriter::be();
291        w.u8(1)
292            .align(4)
293            .u32(0x0102_0304)
294            .set_big_endian(false)
295            .u16(0x0506)
296            .cstr(b"ab");
297        assert_eq!(
298            w.into_inner(),
299            [1, 0, 0, 0, 1, 2, 3, 4, 6, 5, b'a', b'b', 0]
300        );
301    }
302}