Skip to main content

unityrs_core/files/
cab.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/files/File.py, UnityPy/files/SerializedFile.py. See THIRD_PARTY_LICENSES.
2//! Writable resources (`files/File.py:92-121`, `files/SerializedFile.py:362-387`).
3//! Creations join the container's save dictionary. They do not register in
4//! Environment.cabs; reloading the saved parent registers its resource readers.
5//! Creation does not mark a file changed.
6
7use std::sync::{Arc, Mutex, MutexGuard};
8
9use bytes::Bytes;
10
11use super::save::{SaveError, Writer};
12use super::{BundleFile, External, ParentKind, SerializedFile, WebFile};
13use crate::limits::{Charge, Meter, MeteredVec, heap_cost};
14use crate::raw::RawStr;
15use crate::stream::{Endian, ShortArray};
16
17const DEFAULT_NAME: &[u8] = b"CAB-UnityPy_Mod.resS";
18
19/// A shared, appendable resource writer. Clones refer to the same bytes.
20#[derive(Clone)]
21pub struct WriteableCab(triomphe::Arc<CabState>);
22const _: () = crate::send_sync::<WriteableCab>();
23
24struct CabState {
25    name: RawStr,
26    flags: u32,
27    endian: Endian,
28    path: Mutex<Option<RawStr>>,
29    data: Mutex<Writer>,
30    charge: Charge,
31}
32
33impl std::fmt::Debug for WriteableCab {
34    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
35        f.debug_struct("WriteableCab")
36            .field("name", self.name())
37            .finish_non_exhaustive()
38    }
39}
40
41impl WriteableCab {
42    /// Create an empty writer owned by a caller-managed file mapping.
43    /// The caller supplies resource metadata from its current mapping.
44    pub fn new(
45        name: RawStr,
46        flags: u32,
47        endian: Endian,
48        meter: &Arc<Meter>,
49    ) -> Result<Self, SaveError> {
50        let size = heap_cost((size_of::<CabState>() + 16) as u64);
51        let charge = meter.charge(size)?;
52        let state = CabState {
53            name,
54            flags,
55            endian,
56            path: Mutex::new(None),
57            data: Mutex::new(Writer::new(meter, endian)?),
58            charge,
59        };
60        Ok(Self(triomphe::Arc::try_new(state).map_err(|_| {
61            crate::limits::ChargeError::Allocator(meter.allocator_refused(size))
62        })?))
63    }
64
65    /// The dictionary key; the default is `CAB-UnityPy_Mod.resS`.
66    #[must_use]
67    pub fn name(&self) -> &RawStr {
68        &self.0.name
69    }
70    /// Directory flags copied from the first existing `.resS`, or zero.
71    #[must_use]
72    pub fn flags(&self) -> u32 {
73        self.0.flags
74    }
75    /// Endianness copied from that resource, or big endian.
76    #[must_use]
77    pub fn endian(&self) -> Endian {
78        self.0.endian
79    }
80    /// The archive path installed by the last SerializedFile caller.
81    #[must_use]
82    pub fn path(&self) -> Option<RawStr> {
83        lock(&self.0.path).clone()
84    }
85    pub(crate) fn validate_name(
86        &self,
87        layout: super::SaveLayout,
88        web: bool,
89    ) -> Result<(), SaveError> {
90        if layout == super::SaveLayout::Semantic {
91            self.0
92                .charge
93                .meter()
94                .count_decode(self.name().len() as u64)?;
95            let name = self.name().as_bytes();
96            if (!web && name.contains(&0)) || (web && std::str::from_utf8(name).is_err()) {
97                return Err(SaveError::Range("CAB name"));
98            }
99        }
100        Ok(())
101    }
102    /// Append bytes, returning their starting offset. A refusal leaves bytes intact.
103    pub fn write_bytes(&self, bytes: &[u8]) -> Result<u64, SaveError> {
104        let mut data = lock(&self.0.data);
105        let at = super::save::narrow(data.len(), "CAB offset")?;
106        data.bytes(bytes)?;
107        Ok(at)
108    }
109    /// Write at a caller-selected cursor, retaining the tail and zero-filling
110    /// any gap. A refused growth or work charge leaves the bytes unchanged.
111    pub fn write_at(&self, offset: u64, bytes: &[u8]) -> Result<(), SaveError> {
112        let offset = super::save::narrow(offset, "CAB offset")?;
113        lock(&self.0.data).write_at(offset, bytes)
114    }
115    /// Current payload length without materializing a snapshot.
116    #[must_use]
117    pub fn len(&self) -> usize {
118        lock(&self.0.data).len()
119    }
120    /// Whether the resource contains no bytes.
121    #[must_use]
122    pub fn is_empty(&self) -> bool {
123        self.len() == 0
124    }
125    /// Write zero padding at a selected cursor, charging before growth.
126    pub fn write_zeroes_at(&self, offset: u64, count: usize) -> Result<(), SaveError> {
127        let offset = super::save::narrow(offset, "CAB offset")?;
128        lock(&self.0.data).write_zeroes_at(offset, count)
129    }
130    /// Write a signed integer using the inherited endian.
131    pub fn write_i32(&self, value: i32) -> Result<(), SaveError> {
132        lock(&self.0.data).i32(value)
133    }
134    /// A metered snapshot, retaining its charge for as long as any clone lives.
135    pub fn save(&self) -> Result<Bytes, SaveError> {
136        let data = lock(&self.0.data);
137        let mut out = Writer::new(data.meter(), self.endian())?;
138        out.bytes(data.slice())?;
139        out.finish()
140    }
141}
142
143pub(crate) struct WritableCabs(Mutex<MeteredVec<WriteableCab>>);
144
145impl WritableCabs {
146    pub(crate) fn new(meter: &Arc<Meter>) -> Self {
147        Self(Mutex::new(MeteredVec::new(meter)))
148    }
149    pub(crate) fn lock(&self) -> MutexGuard<'_, MeteredVec<WriteableCab>> {
150        lock(&self.0)
151    }
152
153    fn get(
154        &self,
155        name: Option<&RawStr>,
156        files: &[super::FileSlot],
157        directory: &[super::DirEntry],
158        meter: &Arc<Meter>,
159    ) -> Result<WriteableCab, SaveError> {
160        let name = name
161            .filter(|n| !n.is_empty())
162            .cloned()
163            .unwrap_or_else(|| RawStr::from_static(DEFAULT_NAME));
164        let mut cabs = self.lock();
165        for cab in cabs.as_slice() {
166            meter.count_decode(name.len() as u64)?;
167            if cab.name() == &name {
168                return Ok(cab.clone());
169            }
170        }
171        let mut flags = None;
172        for slot in files {
173            meter.count_decode(slot.name.len() as u64 + name.len() as u64)?;
174            if slot.name == name {
175                return Err(SaveError::CabExists);
176            }
177            if flags.is_none() && slot.name.as_bytes().ends_with(b".resS") {
178                flags = Some(
179                    directory
180                        .get(slot.dir_index)
181                        .and_then(|r| r.flags)
182                        .unwrap_or(0),
183                );
184            }
185        }
186        // Earlier writable resources participate in the same dict order.
187        if flags.is_none() {
188            flags = cabs
189                .as_slice()
190                .iter()
191                .find(|c| c.name().as_bytes().ends_with(b".resS"))
192                .map(WriteableCab::flags);
193        }
194        meter.count_decode(name.len() as u64)?;
195        cabs.reserve_exact(1)?;
196        let cab = WriteableCab::new(
197            RawStr::charged(name.as_bytes(), meter)?,
198            flags.unwrap_or(0),
199            Endian::Big,
200            meter,
201        )?;
202        cabs.push(cab.clone())?;
203        Ok(cab)
204    }
205}
206
207macro_rules! container {
208    ($ty:ty) => {
209        impl $ty {
210            /// Create or reuse a resource writer. Existing reader keys refuse.
211            /// Creation alone neither marks changed nor registers an environment CAB.
212            pub fn get_writeable_cab(
213                &self,
214                name: Option<&RawStr>,
215            ) -> Result<WriteableCab, SaveError> {
216                self.writable
217                    .get(name, self.files(), self.directory(), self.meter())
218            }
219            /// The writers added after the loaded files, in dictionary order.
220            pub fn writeable_cabs(&self) -> Result<MeteredVec<WriteableCab>, SaveError> {
221                let cabs = self.writable.lock();
222                self.meter().count_decode(cabs.len() as u64)?;
223                let mut out = MeteredVec::with_capacity(self.meter(), cabs.len())?;
224                for cab in cabs.as_slice() {
225                    out.push(cab.clone())?;
226                }
227                Ok(out)
228            }
229        }
230    };
231}
232container!(BundleFile);
233container!(WebFile);
234
235impl SerializedFile {
236    /// Create a resource in the parent bundle/WebFile and append its external.
237    /// Top-level `SerializedFile`s have no writable CAB, as in UnityPy.
238    pub fn get_writeable_cab(
239        &self,
240        name: Option<&RawStr>,
241    ) -> Result<Option<WriteableCab>, SaveError> {
242        self.get_writeable_cab_with_guid(name, guid_suffix())
243    }
244
245    /// The same operation with the last sixteen ASCII bytes of a UUID URN
246    /// supplied by the caller (the Python binding can pass `uuid.uuid1()`).
247    /// This also makes the otherwise nondeterministic GUID replayable.
248    pub fn get_writeable_cab_with_guid(
249        &self,
250        name: Option<&RawStr>,
251        guid: [u8; 16],
252    ) -> Result<Option<WriteableCab>, SaveError> {
253        let Some(parent) = self.parent() else {
254            return Ok(None);
255        };
256        let name = name
257            .cloned()
258            .unwrap_or_else(|| RawStr::from_static(DEFAULT_NAME));
259        self.meter().count_decode(
260            10u64
261                .saturating_add(self.name().len() as u64)
262                .saturating_add(name.len() as u64),
263        )?;
264        // File.name is a POSIX basename in UnityPy, whereas our stored name
265        // also serves as the container dictionary key.
266        let basename = self
267            .name()
268            .as_bytes()
269            .rsplit(|&b| b == b'/')
270            .next()
271            .unwrap_or_default();
272        let path = RawStr::charged_concat(
273            &[b"archive:/", basename, b"/", name.as_bytes()],
274            self.meter(),
275        )?;
276        self.meter().count_decode(path.len() as u64)?;
277        if path.as_bytes().contains(&0) || path.len() > crate::stream::STRING_TO_NULL_WINDOW {
278            return Err(SaveError::Range("CAB external path"));
279        }
280        let mut pending = lock(&self.pending_externals);
281        self.meter().count_decode(
282            ((self.externals().len() + pending.len()) as u64).saturating_mul(path.len() as u64),
283        )?;
284        let present = self
285            .externals()
286            .iter()
287            .chain(pending.as_slice())
288            .any(|e| e.path == path);
289        if !present {
290            pending.reserve_exact(1)?;
291        }
292        let cab = match &parent.kind {
293            ParentKind::Bundle { bundle, .. } => {
294                bundle.upgrade().map(|b| b.get_writeable_cab(Some(&name)))
295            }
296            ParentKind::Web { web } => web.upgrade().map(|w| w.get_writeable_cab(Some(&name))),
297        }
298        .transpose()?;
299        if let Some(cab) = &cab {
300            if !present {
301                pending.push(External {
302                    temp_empty: Some(RawStr::default()),
303                    guid: Some(ShortArray::from_slice(&guid)),
304                    kind: Some(0),
305                    path: path.clone(),
306                })?;
307            }
308            *lock(&cab.0.path) = Some(path);
309        }
310        Ok(cab)
311    }
312
313    /// Pending metadata additions. Loaded metadata remains the immutable
314    /// `externals()` view, as original object bytes do after `set_raw_data`.
315    pub fn writeable_externals(&self) -> Result<MeteredVec<External>, SaveError> {
316        let pending = lock(&self.pending_externals);
317        self.meter().count_decode(pending.len() as u64)?;
318        let mut out = MeteredVec::with_capacity(self.meter(), pending.len())?;
319        for external in pending.as_slice() {
320            out.push(external.clone())?;
321        }
322        Ok(out)
323    }
324}
325
326fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
327    mutex
328        .lock()
329        .unwrap_or_else(std::sync::PoisonError::into_inner)
330}
331
332fn guid_suffix() -> [u8; 16] {
333    use std::hash::{BuildHasher, Hasher};
334    use std::sync::atomic::{AtomicU64, Ordering};
335    static NODE: AtomicU64 = AtomicU64::new(0);
336    static SEQUENCE: AtomicU64 = AtomicU64::new(0);
337    let node = NODE.load(Ordering::Relaxed);
338    let node = if node == 0 {
339        let mut h = std::collections::hash_map::RandomState::new().build_hasher();
340        h.write_u8(1);
341        let proposed = h.finish() | (1 << 40);
342        match NODE.compare_exchange(0, proposed, Ordering::Relaxed, Ordering::Relaxed) {
343            Ok(_) => proposed,
344            Err(current) => current,
345        }
346    } else {
347        node
348    };
349    let mut h = std::collections::hash_map::RandomState::new().build_hasher();
350    h.write_u64(SEQUENCE.fetch_add(1, Ordering::Relaxed));
351    let value = (h.finish() & 0xfff) << 48 | node & 0xffff_ffff_ffff;
352    let mut out = [b'0'; 16];
353    out[3] = b'-';
354    let mut shift = 56u32;
355    for (i, b) in out.iter_mut().enumerate() {
356        if i == 3 {
357            continue;
358        }
359        *b = b"0123456789abcdef"
360            .get(((value >> shift) & 15) as usize)
361            .copied()
362            .unwrap_or(b'0');
363        shift = shift.saturating_sub(4);
364    }
365    out
366}