Skip to main content

unityrs_core/files/
save.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/streams/EndianBinaryWriter.py. See THIRD_PARTY_LICENSES.
2//! Metered primitives for file and tree writers, following
3//! `streams/EndianBinaryWriter.py:41-97`. Every growth charges memory;
4//! every byte copied or zeroed charges the reader's cumulative work first.
5
6use crate::budget::DecodeBuf;
7use crate::error::{Error, LimitKind};
8use crate::limits::{ChargeError, Meter};
9use crate::stream::Endian;
10use bytes::Bytes;
11use std::sync::Arc;
12
13/// File layout and the blob writer's common-string offset-zero rule.
14#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
15pub enum SaveLayout {
16    /// Reloadable and idempotent: common offset zero and sequential metadata
17    /// strings at the reader window boundary use corrected spellings (Tier C).
18    /// Emitted GUIDs and hashes must contain exactly 16 bytes.
19    #[default]
20    Semantic,
21    /// UnityPy's layout, including its local spelling of common offset zero.
22    /// Tier C old trees and pre-v9 headers still use the corrected layout.
23    UnityPy,
24}
25
26/// Options for `SerializedFile::save`. Packers belong to the enclosing bundle.
27#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
28pub struct SaveOptions {
29    /// The layout to emit.
30    pub layout: SaveLayout,
31}
32
33/// A writer refusal. No assertion, narrowing cast or allocation may panic.
34#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
35#[non_exhaustive]
36pub enum SaveError {
37    /// A writable CAB key already names a loaded reader.
38    #[error("this CAB already exists and is not a writer")]
39    CabExists,
40    /// Serialized formats above 26 and bundle formats above 9 are outside
41    /// the pinned HEAD writer's supported formats.
42    #[error("HEAD-tier writes are not implemented")]
43    HeadTierWritesNotImplemented,
44    /// A file kind or layout whose writer is outside this implementation.
45    #[error("save is not implemented for {0}")]
46    Unsupported(&'static str),
47    /// A codec without a UnityPy compression function.
48    #[error("compression is not implemented for {0:?}")]
49    UnsupportedCodec(crate::codec::Codec),
50    /// The encoder refused the input or could not finish its stream.
51    #[error("{codec:?} compression failed: {detail}")]
52    Compress {
53        /// The selected compression algorithm.
54        codec: crate::codec::Codec,
55        /// A fixed diagnostic (no unmetered error allocation).
56        detail: &'static str,
57    },
58    /// The input's meter refused work, or its meter, budget or allocator
59    /// refused storage.
60    #[error(transparent)]
61    Charge(#[from] ChargeError),
62    /// An original object's reader refused its byte range.
63    #[error(transparent)]
64    Read(#[from] Error),
65    /// Reserializing the object's typetree failed before installing data.
66    #[error(transparent)]
67    Object(#[from] crate::walk::WriteError),
68    /// A length or integer cannot be represented by the selected format.
69    #[error("save field {0} is out of range")]
70    Range(&'static str),
71    /// A required field is absent (UnityPy's assertion or struct error).
72    #[error("save field {0} is missing")]
73    Missing(&'static str),
74}
75
76pub(crate) fn required<T>(value: Option<T>, name: &'static str) -> Result<T, SaveError> {
77    value.ok_or(SaveError::Missing(name))
78}
79
80pub(crate) fn narrow<T: TryFrom<U>, U>(value: U, name: &'static str) -> Result<T, SaveError> {
81    T::try_from(value).map_err(|_| SaveError::Range(name))
82}
83
84pub(crate) struct Writer {
85    buf: DecodeBuf,
86    endian: Endian,
87    sequential_window: bool,
88    window_tail: bool,
89}
90
91impl Writer {
92    pub(crate) fn new(meter: &Arc<Meter>, endian: Endian) -> Result<Self, SaveError> {
93        Ok(Self {
94            buf: DecodeBuf::counted(meter, u64::MAX, LimitKind::InputMemory)?,
95            endian,
96            sequential_window: false,
97            window_tail: false,
98        })
99    }
100    pub(crate) fn metadata(
101        meter: &Arc<Meter>,
102        endian: Endian,
103        layout: SaveLayout,
104    ) -> Result<Self, SaveError> {
105        let mut out = Self::new(meter, endian)?;
106        out.sequential_window = layout == SaveLayout::Semantic;
107        Ok(out)
108    }
109    pub(crate) fn meter(&self) -> &Arc<Meter> {
110        self.buf.meter()
111    }
112    pub(crate) fn len(&self) -> usize {
113        self.buf.len()
114    }
115    pub(crate) fn bytes(&mut self, b: &[u8]) -> Result<(), SaveError> {
116        self.buf.extend_from_slice(b)?;
117        if !b.is_empty() {
118            self.window_tail = false;
119        }
120        Ok(())
121    }
122    pub(crate) fn write_at(&mut self, offset: usize, bytes: &[u8]) -> Result<(), SaveError> {
123        self.buf.write_at(offset, bytes)?;
124        Ok(())
125    }
126    pub(crate) fn write_zeroes_at(&mut self, offset: usize, count: usize) -> Result<(), SaveError> {
127        self.buf.write_zeroes_at(offset, count)?;
128        Ok(())
129    }
130    pub(crate) fn slice(&self) -> &[u8] {
131        self.buf.as_slice()
132    }
133    pub(crate) fn finish(self) -> Result<Bytes, SaveError> {
134        Ok(self.buf.into_bytes()?)
135    }
136    pub(crate) fn align(&mut self, n: usize) -> Result<(), SaveError> {
137        let padding = (n - self.len() % n) % n;
138        self.buf.grow_zeroed(padding)?;
139        if padding != 0 {
140            self.window_tail = false;
141        }
142        Ok(())
143    }
144    pub(crate) fn cstr(&mut self, b: &[u8]) -> Result<(), SaveError> {
145        // A sequential reader consumes exactly its window when no NUL is
146        // found. Appending one at that boundary shifts the following field.
147        // Blob string buffers have explicit offsets and retain their NULs.
148        if self.sequential_window && b.len() > crate::stream::STRING_TO_NULL_WINDOW {
149            return Err(SaveError::Range("metadata string window"));
150        }
151        self.bytes(b)?;
152        if self.sequential_window && b.len() == crate::stream::STRING_TO_NULL_WINDOW {
153            self.window_tail = true;
154            return Ok(());
155        }
156        self.bytes(&[0])
157    }
158    /// A memory reader requires at least one byte beyond an unterminated
159    /// full window. Retain a sentinel when that window ends the metadata;
160    /// the next save reconstructs it, so it is idempotent even at EOF.
161    pub(crate) fn end_metadata(&mut self) -> Result<(), SaveError> {
162        if self.window_tail {
163            self.bytes(&[0])?;
164        }
165        Ok(())
166    }
167    pub(crate) fn fixed16(&mut self, b: &[u8], field: &'static str) -> Result<(), SaveError> {
168        // A negative memory-reader position can produce a short GUID/hash
169        // and still let subsequent fields parse. Such a record has no valid
170        // sequential spelling; layout mode retains UnityPy's short write.
171        if self.sequential_window && b.len() != 16 {
172            return Err(SaveError::Range(field));
173        }
174        self.bytes(b)
175    }
176    pub(crate) fn boolean(&mut self, v: bool) -> Result<(), SaveError> {
177        self.bytes(&[u8::from(v)])
178    }
179    pub(crate) fn count(&mut self, n: usize) -> Result<(), SaveError> {
180        self.i32(narrow(n, "count")?)
181    }
182    pub(crate) fn number<const N: usize>(&mut self, mut little: [u8; N]) -> Result<(), SaveError> {
183        if self.endian == Endian::Big {
184            little.reverse();
185        }
186        self.bytes(&little)
187    }
188    pub(crate) fn i16(&mut self, n: i16) -> Result<(), SaveError> {
189        self.number(n.to_le_bytes())
190    }
191    pub(crate) fn u16(&mut self, n: u16) -> Result<(), SaveError> {
192        self.number(n.to_le_bytes())
193    }
194    pub(crate) fn i32(&mut self, n: i32) -> Result<(), SaveError> {
195        self.number(n.to_le_bytes())
196    }
197    pub(crate) fn u32(&mut self, n: u32) -> Result<(), SaveError> {
198        self.number(n.to_le_bytes())
199    }
200    pub(crate) fn i64(&mut self, n: i64) -> Result<(), SaveError> {
201        self.number(n.to_le_bytes())
202    }
203    pub(crate) fn u64(&mut self, n: u64) -> Result<(), SaveError> {
204        self.number(n.to_le_bytes())
205    }
206}
207
208#[cfg(test)]
209mod tests {
210    use super::*;
211    use crate::budget::{Reservation, Unbounded};
212
213    /// Independent writer evidence: the crate's reader recovers each scalar
214    /// and the original surrogate-escaped string bytes in either byte order.
215    #[test]
216    fn primitives_and_null_strings_roundtrip_through_the_reader() {
217        use crate::stream::Reader;
218
219        for endian in [Endian::Big, Endian::Little] {
220            let meter =
221                Meter::with_decode_work(1 << 20, 1 << 20, Arc::new(Unbounded), Reservation::Input);
222            let mut writer = Writer::new(&meter, endian).unwrap();
223            writer.boolean(true).unwrap();
224            writer.boolean(false).unwrap();
225            writer.i16(i16::MIN).unwrap();
226            writer.u16(u16::MAX).unwrap();
227            writer.i32(i32::MIN).unwrap();
228            writer.u32(u32::MAX).unwrap();
229            writer.i64(i64::MIN).unwrap();
230            writer.u64(u64::MAX).unwrap();
231            writer.cstr(b"a\xff\xc3\xa9").unwrap();
232            let unaligned = writer.len();
233            writer.align(8).unwrap();
234            assert!(writer.slice()[unaligned..].iter().all(|byte| *byte == 0));
235            let bytes = writer.finish().unwrap();
236            assert_eq!(meter.decoded(), bytes.len() as u64);
237            assert!(meter.used() > 0);
238            let mut reader = Reader::new(&bytes, endian);
239            assert!(reader.read_bool().unwrap());
240            assert!(!reader.read_bool().unwrap());
241            assert_eq!(reader.read_i16().unwrap(), i16::MIN);
242            assert_eq!(reader.read_u16().unwrap(), u16::MAX);
243            assert_eq!(reader.read_i32().unwrap(), i32::MIN);
244            assert_eq!(reader.read_u32().unwrap(), u32::MAX);
245            assert_eq!(reader.read_i64().unwrap(), i64::MIN);
246            assert_eq!(reader.read_u64().unwrap(), u64::MAX);
247            assert_eq!(reader.read_string_to_null().unwrap(), b"a\xff\xc3\xa9");
248            reader.align(8).unwrap();
249            assert_eq!(reader.position(), bytes.len() as i128);
250            drop(bytes);
251            assert_eq!(meter.used(), 0);
252        }
253    }
254
255    #[test]
256    fn positioned_writes_preserve_tails_and_refusals_preserve_bytes() {
257        let meter = Meter::with_decode_work(1 << 20, 2048, Arc::new(Unbounded), Reservation::Input);
258        let mut writer = Writer::new(&meter, Endian::Little).unwrap();
259        writer.bytes(b"abc").unwrap();
260        writer.write_at(0, b"Z").unwrap();
261        writer.write_at(5, b"Q").unwrap();
262        assert_eq!(writer.slice(), b"Zbc\0\0Q");
263        writer.write_at(100, b"").unwrap();
264        assert_eq!(writer.slice(), b"Zbc\0\0Q");
265        let before = meter.used();
266        let work = meter.decoded();
267        let held = meter.charge(meter.limit() - before).unwrap();
268        let error = writer.write_at(1, &[b'x'; 1024]).unwrap_err();
269        assert!(matches!(error, SaveError::Charge(ChargeError::Limit(_))));
270        assert_eq!(writer.slice(), b"Zbc\0\0Q");
271        assert_eq!(meter.decoded(), work);
272        drop(held);
273        writer.write_at(1, &[b'x'; 1024]).unwrap();
274        assert_eq!(writer.len(), 1025);
275        assert_eq!(writer.slice().first(), Some(&b'Z'));
276        meter.count_decode(2048 - meter.decoded()).unwrap();
277        let error = writer.write_at(0, b"W").unwrap_err();
278        assert!(matches!(error, SaveError::Charge(ChargeError::Limit(_))));
279        assert_eq!(writer.slice().first(), Some(&b'Z'));
280    }
281
282    #[test]
283    fn memory_refused_alignment_can_retry_with_its_exact_work_allowance() {
284        let meter = Meter::with_decode_work(1 << 20, 16, Arc::new(Unbounded), Reservation::Input);
285        let mut writer = Writer::new(&meter, Endian::Little).unwrap();
286        writer.bytes(&[7; 8]).unwrap();
287        let before = meter.used();
288        let held = meter.charge(meter.limit() - before).unwrap();
289        let SaveError::Charge(ChargeError::Limit(error)) = writer.align(16).unwrap_err() else {
290            panic!("alignment must refuse memory")
291        };
292        assert_eq!(error.kind(), LimitKind::InputMemory);
293        assert_eq!(writer.slice(), &[7; 8]);
294        assert_eq!(meter.decoded(), 8, "refused padding writes nothing");
295        drop(held);
296        assert_eq!(meter.used(), before);
297        writer.align(16).unwrap();
298        assert_eq!(
299            writer.slice(),
300            &[7, 7, 7, 7, 7, 7, 7, 7, 0, 0, 0, 0, 0, 0, 0, 0]
301        );
302        assert_eq!(meter.decoded(), 16);
303        drop(writer);
304        assert_eq!(meter.used(), 0);
305    }
306}