Skip to main content

unityrs_core/env/
resource_data.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/ResourceReader.py, UnityPy/classes/PPtr.py, UnityPy/files/SerializedFile.py. See THIRD_PARTY_LICENSES.
2//! [`Environment::resource`]: UnityPy's `get_resource_data`, over the
3//! candidates of [`super::resource`]. "Module docs" below are [`super`]'s.
4
5use std::sync::Arc;
6
7use bytes::Bytes;
8
9use super::load::Asked;
10use super::registry::{Slot, Through, entry_of};
11use super::{Cab, Candidate, Environment, LoadMode, RawCab, resource_candidates};
12use crate::error::{Error, NotFound};
13use crate::files::{BundleFile, File, Parent, ParentKind, SerializedFile};
14use crate::raw::RawStr;
15
16/// `ResourceReader._get_resource_data(reader, offset, size)`
17/// (`helpers/ResourceReader.py:36-38`): `reader.Position = offset;
18/// reader.read_bytes(size)`, by the reader's rules: a bundle entry's and a
19/// file of bytes' are a Python slice of the reader's bytes; a file loaded
20/// from a path is a stream, which takes the offset and reads the size by
21/// the stream reader's rules ([`crate::stream::ReaderKind::seek`] and
22/// [`crate::stream::ReaderKind::read_u64`]; `PARITY.md` section 13). An
23/// offset past the largest file the file system takes, or a size the
24/// machine cannot allocate, is UnityPy's `OSError` or `MemoryError` on that
25/// machine, and reads short or nothing here (section 19.3's row "a path's
26/// stream past the machine's limits"). Review round 10: this restated a
27/// bound for the size that was not the reader's.
28fn read_cab(cab: &Cab, offset: u64, size: u64) -> Result<Bytes, Error> {
29    match cab {
30        Cab::Raw(RawCab::InBundle { bundle, dir_index }) => {
31            bundle.entry_range(*dir_index, offset..offset.saturating_add(size))
32        }
33        Cab::Raw(RawCab::File(raw)) => {
34            let kind = raw.reader_kind();
35            let at = kind.seek(i128::from(offset))?;
36            let (range, _) = kind.read_u64(raw.data.len(), at, size)?;
37            Ok(raw.data.slice(range))
38        }
39        Cab::Serialized(sf) => Err(not_a_reader(sf.name())),
40    }
41}
42
43/// A `SerializedFile` asked for resource bytes: it has no `read_bytes`
44/// (an `AttributeError` in UnityPy).
45fn not_a_reader(name: &RawStr) -> Error {
46    Error::Malformed {
47        what: "resource",
48        detail: format!("{name} is a SerializedFile, not a reader").into(),
49    }
50}
51
52impl Environment {
53    /// `get_resource_data(path, from, offset, size)`
54    /// (`helpers/ResourceReader.py:10-38`). The candidate is resolved by
55    /// UnityPy's rule (the registry, then dependencies), but each candidate's
56    /// slot is first *located* without being parsed. When the core can tell,
57    /// without reading anything, that the slot is an entry of `from`'s own
58    /// input, the entry is read through `from`'s bundle and the shared slot
59    /// is never parsed, so neither the resolution nor the read decodes
60    /// anything through the shared handle or charges its pool (plan section
61    /// 3.13): the slot's open handle is `from`'s bundle itself, or the slot
62    /// is a [`Source::Bytes`](super::Source::Bytes) whose `Bytes` are `from`'s bundle's source (the
63    /// same allocation and range) at the entry's directory index. A slot whose
64    /// source is a [`Source::Path`](super::Source::Path) or
65    /// [`Source::Fetch`](super::Source::Fetch) and whose handle is
66    /// not open (evicted) cannot be compared without opening it again, so it
67    /// resolves by UnityPy's rule, through the slot. Which of the two a batch
68    /// engine's inputs get is its design (`docs/plans/batch.md`).
69    /// The answer is the same entry's either way. The fallback (the file's
70    /// externals and the candidates, loaded when no candidate is
71    /// registered) loads through the resolver as UnityPy's
72    /// `load_dependencies` does: with [`EnvOptions::keep_resolver_loads`]
73    /// each file it loads is a non-dependency [`FileEntry`] under the name
74    /// asked, whose objects and rows [`Self::objects`] and
75    /// [`Self::container`] list, loaded again by a later fallback (module
76    /// docs); without it, an LRU dependency. `path` is the object's
77    /// string, so the candidates are slices of it
78    /// ([`resource::resource_candidates`]), and each whole name and lowered
79    /// key a lookup builds is charged to `from`'s meter while it lives.
80    ///
81    /// A pool refusal (a read or a lookup from a dependency's file) evicts
82    /// the others and retries once, `from`'s top-level bundle held
83    /// meanwhile: each lookup of the candidates, and each candidate's name
84    /// with its fallback load; and every fallback load, an external's as a
85    /// candidate's, listed or not, takes its own retry
86    /// (`Environment::load_resolved`), a refusal its fetcher returns
87    /// included, so a retry never loads again what a load before it loaded
88    /// (plan section 3.13; review round 8: the read had no retry; review
89    /// round 12: an external's load listed under `keep_resolver_loads`
90    /// returned its fetcher's refusal untried).
91    ///
92    /// [`EnvOptions::keep_resolver_loads`]: super::EnvOptions::keep_resolver_loads
93    /// [`FileEntry`]: super::FileEntry
94    /// [`resource::resource_candidates`]: super::resource::resource_candidates
95    pub fn resource(
96        &self,
97        from: &Arc<SerializedFile>,
98        path: &RawStr,
99        offset: u64,
100        size: u64,
101    ) -> Result<Bytes, Error> {
102        let _top = top_container(from);
103        // UnityPy helpers/ResourceReader.py:11-33
104        let candidates = resource_candidates(path);
105        let first = self.room(|| {
106            self.reach_chain(from)?;
107            self.resource_try(from, &candidates, offset, size)
108        })?;
109        if let Some(bytes) = first {
110            return Ok(bytes);
111        }
112        // :26: `assets_file.load_dependencies(possible_names)`
113        // (files/SerializedFile.py:330-349): every external, then every
114        // candidate, through `load_file(name, True)`.
115        let meter = from.meter();
116        for external in from.externals() {
117            self.fallback_load(&external.path)?;
118        }
119        for c in &candidates {
120            self.room(|| self.fallback_candidate(c, meter))?;
121        }
122        if let Some(bytes) = self.room(|| self.resource_try(from, &candidates, offset, size))? {
123            return Ok(bytes);
124        }
125        let [basename, ..] = candidates;
126        Err(Error::NotFound(NotFound::Resource(basename.stem)))
127    }
128
129    /// `load_file(name, True)` for a resource fallback: what the resolver
130    /// returns for `name`, if anything.
131    fn fallback_load(&self, name: &RawStr) -> Result<(), Error> {
132        let Some(resolver) = self.inner.options.resolver.as_ref() else {
133            return Ok(());
134        };
135        let Some(source) = resolver.resolve(name.as_bytes()) else {
136            return Ok(());
137        };
138        self.load_resolved(&source, Asked::Fallback(name)).map(drop)
139    }
140
141    /// Lookup temporaries never need a shared owner. Only a successful load
142    /// persists its registered name in fallible shared storage, so a suffixed
143    /// resolver hit cannot abort while promoting its temporary name.
144    fn fallback_candidate(
145        &self,
146        candidate: &Candidate,
147        meter: &Arc<crate::limits::Meter>,
148    ) -> Result<(), Error> {
149        let name = candidate.joined_vec(meter)?;
150        let Some(resolver) = self.inner.options.resolver.as_ref() else {
151            return Ok(());
152        };
153        let Some(source) = resolver.resolve(name.as_slice()) else {
154            return Ok(());
155        };
156        let persistent = RawStr::from_metered(name, meter)?;
157        self.load_resolved(&source, Asked::Fallback(&persistent))
158            .map(drop)
159    }
160
161    /// The first candidate a registered slot answers, read.
162    fn resource_try(
163        &self,
164        from: &Arc<SerializedFile>,
165        candidates: &[Candidate; 4],
166        offset: u64,
167        size: u64,
168    ) -> Result<Option<Bytes>, Error> {
169        let meter = from.meter();
170        for c in candidates {
171            let name = c.joined_vec(meter)?;
172            let Some(slot) = self.inner.registry.slot_bytes(name.as_slice(), meter)? else {
173                continue;
174            };
175            drop(name);
176            if let Some((bundle, i)) = own_entry(from, &slot) {
177                // Read through `from`'s own bundle: the slot is not parsed.
178                match bundle.entry(i)? {
179                    File::Raw(_) => {
180                        return Ok(Some(
181                            bundle.entry_range(i, offset..offset.saturating_add(size))?,
182                        ));
183                    }
184                    File::Serialized(sf) => return Err(not_a_reader(sf.name())),
185                    File::Bundle(nested) => {
186                        self.inner.registry.reach(&slot, Some(&nested))?;
187                        continue;
188                    }
189                    File::Web(w) => {
190                        self.inner.registry.reach_web(&slot, &w)?;
191                        continue;
192                    }
193                }
194            }
195            if let Some(cab) = self.inner.registry.resolve(&slot)? {
196                return Ok(Some(read_cab(&cab, offset, size)?));
197            }
198        }
199        Ok(None)
200    }
201}
202
203impl Environment {
204    /// Under [`LoadMode::Lazy`], reaches the nested container on `from`'s
205    /// own chain before a lookup from it answers (the registry's module
206    /// docs): the container below `from`'s top-level bundle, whose reach
207    /// registers its whole subtree, when the slot under its name is that
208    /// very entry, or stands in for it ([`reach_entry`]). When the slot is
209    /// another entry's, `from`'s container was dropped by a later
210    /// registration, which reached it then. Under `Eager` a nested container
211    /// is registered at load. Walks up `from`'s parents only (as deep as
212    /// [`crate::limits::Limits::max_container_depth`]), allocating nothing.
213    pub(super) fn reach_chain(&self, from: &SerializedFile) -> Result<(), Error> {
214        if self.inner.options.load != LoadMode::Lazy {
215            return Ok(());
216        }
217        let Some(mut top) = parent_container(from.parent()) else {
218            return Ok(());
219        };
220        let mut below = None;
221        while let Some(up) = parent_container(container_parent(&top)) {
222            below = Some(std::mem::replace(&mut top, up));
223        }
224        let Some(nested) = below else {
225            return Ok(());
226        };
227        let name = match &nested {
228            File::Bundle(b) => b.name(),
229            File::Web(w) => w.name(),
230            _ => return Ok(()),
231        };
232        let Some(slot) = self.inner.registry.slot(name, nested.meter())? else {
233            return Ok(());
234        };
235        match top {
236            File::Bundle(b) => self.reach_entry(&b, &slot, &nested),
237            _ => Ok(()),
238        }
239    }
240
241    /// A pointer reached `nested`, `from`'s sibling at `dir_index` of its
242    /// bundle `bundle`, by the bundle's names (`classes/PPtr.py:75-78`):
243    /// under [`LoadMode::Lazy`] it is reached as a `get` of its name would
244    /// reach it, when the slot under its name is that entry, or stands in
245    /// for it ([`reach_entry`]).
246    pub(super) fn reach_sibling(
247        &self,
248        from: &SerializedFile,
249        bundle: &Arc<BundleFile>,
250        dir_index: usize,
251        nested: &File,
252    ) -> Result<(), Error> {
253        if self.inner.options.load != LoadMode::Lazy {
254            return Ok(());
255        }
256        let Some(d) = bundle.directory().get(dir_index) else {
257            return Ok(());
258        };
259        let Some(slot) = self.inner.registry.slot(&d.path, from.meter())? else {
260            return Ok(());
261        };
262        self.reach_entry(bundle, &slot, nested)
263    }
264
265    /// Reaches `slot` when it is `nested`, the asking file's handle on a
266    /// nested container of its bundle `bundle`, as [`entry_of`] tells it:
267    /// from `nested` when the slot reads through `bundle` itself
268    /// ([`Through::Own`]), through the slot's own handle when it stands in
269    /// for that entry ([`Through::Slot`], a reload's slot: review round 5
270    /// found the earlier load's files reached nothing).
271    fn reach_entry(
272        &self,
273        bundle: &Arc<BundleFile>,
274        slot: &Arc<Slot>,
275        nested: &File,
276    ) -> Result<(), Error> {
277        let Some((i, through)) = entry_of(bundle, slot) else {
278            return Ok(());
279        };
280        let same = match (bundle.entry(i)?, nested) {
281            (File::Bundle(a), File::Bundle(b)) => Arc::ptr_eq(&a, b),
282            (File::Web(a), File::Web(b)) => Arc::ptr_eq(&a, b),
283            _ => false,
284        };
285        if !same {
286            return Ok(());
287        }
288        let reg = &self.inner.registry;
289        match (through, nested) {
290            (Through::Own, File::Bundle(b)) => reg.reach(slot, Some(b)),
291            (Through::Own, File::Web(w)) => reg.reach_web(slot, w),
292            _ => reg.reach(slot, None),
293        }
294    }
295}
296
297/// The top-level bundle `from` is read through, while it is alive: its
298/// container's container, and so on up. A call that reads from `from` holds
299/// it, so an eviction while it runs (its own retry's, another thread's)
300/// drops only the LRU's handle, and the chain the call reads through stays.
301pub(super) fn top_container(from: &SerializedFile) -> Option<File> {
302    let mut top = parent_container(from.parent())?;
303    while let Some(up) = parent_container(container_parent(&top)) {
304        top = up;
305    }
306    Some(top)
307}
308fn container_parent(file: &File) -> Option<&Parent> {
309    match file {
310        File::Bundle(b) => b.parent(),
311        File::Web(w) => w.parent(),
312        _ => None,
313    }
314}
315fn parent_container(parent: Option<&Parent>) -> Option<File> {
316    match &parent?.kind {
317        ParentKind::Bundle { bundle, .. } => bundle.upgrade().map(File::Bundle),
318        ParentKind::Web { web } => web.upgrade().map(File::Web),
319    }
320}
321
322/// The bundle a parent link names, while it is alive.
323fn parent_bundle(parent: Option<&Parent>) -> Option<Arc<BundleFile>> {
324    match &parent?.kind {
325        ParentKind::Bundle { bundle, .. } => bundle.upgrade(),
326        ParentKind::Web { .. } => None,
327    }
328}
329
330/// When `slot` is an entry of `from`'s own input read through `from`'s own
331/// bundle ([`Through::Own`]: the core can tell without reading anything,
332/// plan section 3.13), that bundle and the entry's directory index.
333fn own_entry(from: &SerializedFile, slot: &Slot) -> Option<(Arc<BundleFile>, usize)> {
334    let fb = parent_bundle(from.parent())?;
335    match entry_of(&fb, slot)? {
336        (i, Through::Own) => Some((fb, i)),
337        (_, Through::Slot) => None,
338    }
339}