Skip to main content

unityrs_core/env/
deref.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/classes/PPtr.py, UnityPy/environment.py. See THIRD_PARTY_LICENSES.
2//! Lookups and dereference: `get_cab`, `find_file` and `PPtr.deref`, by
3//! the rules of [`super::pptr`]. "Module docs" below are [`super`]'s.
4
5use std::hash::{Hash, Hasher};
6use std::sync::Arc;
7
8use super::container_index::Siblings;
9use super::listing::FileMatch;
10use super::load::Asked;
11use super::registry::from_callers;
12use super::registry::{Slot, SlotKind};
13use super::resource_data::top_container;
14use super::{Cab, DerefError, Environment, Found, HeldCab, PPtr, RawCab, pptr};
15use crate::error::{Error, NotFound};
16use crate::files::{External, File, FileSlot, ParentKind, SerializedFile};
17use crate::limits::Meter;
18use crate::object::ObjectRef;
19use crate::pystr::{clean_external_path, lower_eq, simplify_name};
20use crate::raw::RawStr;
21
22/// `objects[m_PathID]` of a target file (rule 6).
23fn object_in(sf: &Arc<SerializedFile>, path_id: i64) -> Result<ObjectRef, DerefError> {
24    sf.object(path_id).ok_or_else(|| DerefError::MissingObject {
25        file: sf.name().clone(),
26        path_id,
27    })
28}
29
30/// The file a CAB is: the `SerializedFile`, or the raw reader (a bundle
31/// entry's, read from its bundle's cell).
32fn cab_file(cab: &Cab) -> Result<File, Error> {
33    Ok(match cab {
34        Cab::Serialized(sf) => File::Serialized(sf.clone()),
35        Cab::Raw(RawCab::File(raw)) => File::Raw(raw.clone()),
36        Cab::Raw(RawCab::InBundle { bundle, dir_index }) => bundle.entry(*dir_index)?,
37    })
38}
39
40/// How [`Environment::external`] reached the file it found, which says how
41/// long a container preload walk may keep the answer (UnityPy keeps none:
42/// each dereference looks again, `classes/PPtr.py:57-85`).
43#[derive(Clone, Copy, Debug, PartialEq, Eq)]
44pub(super) enum Reached {
45    /// A sibling in the asking file's bundle, whose names never change.
46    Sibling,
47    /// This Environment's `files` or registry, which a load may change.
48    Lookup,
49    /// The resolver's file, loaded now: under the name it was asked for or
50    /// another, which only the next lookup tells.
51    Load,
52}
53
54pub(super) struct HeldLookup<'a> {
55    meter: &'a Meter,
56    container: Option<File>,
57    reuse: Option<&'a mut ReuseTarget<'a>>,
58}
59
60type ReuseTarget<'a> = dyn FnMut(FileOccurrence) -> Result<Option<ObjectRef>, Error> + 'a;
61
62impl HeldLookup<'_> {
63    fn reused(
64        &mut self,
65        occurrence: impl FnOnce() -> Option<FileOccurrence>,
66    ) -> Result<Option<ObjectRef>, Error> {
67        match (self.reuse.as_mut(), occurrence) {
68            (Some(reuse), occurrence) => occurrence().map_or(Ok(None), reuse),
69            (None, _) => Ok(None),
70        }
71    }
72}
73
74/// A serialized file's occurrence, comparable before its data is loaded.
75/// Dependency occurrences are stable across cache reopens.
76#[derive(Clone, Debug)]
77pub struct FileOccurrence(Occurrence);
78
79const _: () = crate::send_sync::<FileOccurrence>();
80
81#[derive(Clone, Debug)]
82enum Occurrence {
83    Parsed(Arc<SerializedFile>),
84    Dependency(usize, Arc<Slot>),
85    DependencySibling(Arc<SerializedFile>, usize),
86}
87
88impl FileOccurrence {
89    /// The occurrence of an already parsed file.
90    #[must_use]
91    pub fn of(file: &Arc<SerializedFile>) -> Self {
92        Self(Occurrence::Parsed(file.clone()))
93    }
94
95    fn in_entry(container: &File, index: usize) -> Option<Self> {
96        match container.parsed_container_entry(index)? {
97            File::Serialized(file) => Some(Self::of(file)),
98            _ => None,
99        }
100    }
101
102    fn in_sibling(from: &Arc<SerializedFile>, container: &File, index: usize) -> Option<Self> {
103        if from.occurrence_key().1.is_empty() {
104            Self::in_entry(container, index)
105        } else {
106            Some(Self(Occurrence::DependencySibling(from.clone(), index)))
107        }
108    }
109
110    fn in_slot(slot: &Arc<Slot>) -> Option<Self> {
111        match &slot.kind {
112            SlotKind::Dependency { dep } => Some(Self(Occurrence::Dependency(
113                dep.meter().input_address(),
114                slot.clone(),
115            ))),
116            SlotKind::Ready(Cab::Serialized(file)) => Some(Self::of(file)),
117            SlotKind::Entry { bundle, dir_index } => {
118                Self::in_entry(&File::Bundle(bundle.clone()), *dir_index)
119            }
120            SlotKind::Ready(_) => None,
121        }
122    }
123
124    fn parts(&self) -> (usize, &[usize], Option<usize>) {
125        match &self.0 {
126            Occurrence::Parsed(file) => {
127                let (input, path) = file.occurrence_key();
128                (input, path, None)
129            }
130            Occurrence::Dependency(input, slot) => (*input, slot.rank.path(), None),
131            Occurrence::DependencySibling(from, index) => {
132                let (input, path) = from.occurrence_key();
133                (
134                    input,
135                    path.split_last().map_or(&[], |(_, parent)| parent),
136                    Some(*index),
137                )
138            }
139        }
140    }
141
142    /// Number of directory indices in this occurrence, for work accounting.
143    #[must_use]
144    pub fn path_len(&self) -> usize {
145        let (_, path, last) = self.parts();
146        path.len() + usize::from(last.is_some())
147    }
148}
149
150impl PartialEq for FileOccurrence {
151    fn eq(&self, other: &Self) -> bool {
152        let (input, path, last) = self.parts();
153        let (other_input, other_path, other_last) = other.parts();
154        input == other_input
155            && path
156                .iter()
157                .copied()
158                .chain(last)
159                .eq(other_path.iter().copied().chain(other_last))
160    }
161}
162
163impl Eq for FileOccurrence {}
164
165impl Hash for FileOccurrence {
166    fn hash<H: Hasher>(&self, state: &mut H) {
167        let (input, path, last) = self.parts();
168        input.hash(state);
169        (path.len() + usize::from(last.is_some())).hash(state);
170        for index in path.iter().copied().chain(last) {
171            index.hash(state);
172        }
173    }
174}
175
176fn scan_siblings(
177    slots: &[FileSlot],
178    clean: &RawStr,
179    work: Option<&Meter>,
180) -> Result<Option<usize>, Error> {
181    for slot in slots {
182        if let Some(work) = work {
183            work.count_decode((slot.name.as_bytes().len() as u64).saturating_add(1))?;
184        }
185        if lower_eq(slot.name.as_bytes(), clean.as_bytes()) {
186            return Ok(Some(slot.dir_index));
187        }
188    }
189    Ok(None)
190}
191
192fn external_name<'a>(
193    from: &'a SerializedFile,
194    file_id: i32,
195    work: Option<&Meter>,
196) -> Result<(&'a External, RawStr), DerefError> {
197    let externals = from.externals();
198    let index = pptr::external_index(file_id, externals.len()).map_err(|error| match error {
199        pptr::ExternalIndexError::PastEnd => DerefError::FileIdPastEnd { file_id },
200        pptr::ExternalIndexError::BelowStart => DerefError::FileIdBelowStart { file_id },
201    })?;
202    let external = externals
203        .get(index)
204        .ok_or(DerefError::FileIdBelowStart { file_id })?;
205    if let Some(work) = work {
206        work.count_decode(external.path.len() as u64)
207            .map_err(Error::from)?;
208    }
209    let clean = clean_external_path(&external.path, from.meter()).map_err(Error::from)?;
210    Ok((external, clean))
211}
212
213fn sibling_entry(
214    from: &SerializedFile,
215    clean: &RawStr,
216    siblings: Option<&mut Siblings>,
217    work: Option<&Meter>,
218) -> Result<Option<(File, usize)>, DerefError> {
219    let Some(parent) = from.parent() else {
220        return Ok(None);
221    };
222    let dropped = || DerefError::ContainerDropped {
223        name: parent.name.clone(),
224    };
225    let container = match &parent.kind {
226        ParentKind::Bundle { bundle, .. } => File::Bundle(bundle.upgrade().ok_or_else(dropped)?),
227        ParentKind::Web { web } => File::Web(web.upgrade().ok_or_else(dropped)?),
228    };
229    let index = match (siblings, &container) {
230        (Some(index), File::Bundle(bundle)) => index.find(bundle, clean)?,
231        _ => scan_siblings(container.container_files(), clean, work)?,
232    };
233    Ok(index.map(|index| (container, index)))
234}
235
236impl Environment {
237    /// `get_cab`: the registry under `simplify_name(name)`, an entry parsed
238    /// now if it was registered lazily. The lowered key a lookup builds is
239    /// charged to `meter` while the lookup runs (the meter of the file whose
240    /// input chose `name`; a caller's own string may use
241    /// [`Meter::unlimited`]), and a name already in its simplified form is
242    /// not copied ([`Registry::get`]). A dependency's CAB may outlive its
243    /// bundle in the LRU: [`Self::get_cab_held`] returns the handle that
244    /// keeps it. A pool refusal anywhere in the lookup, the key's charge to
245    /// a dependency's meter included, evicts the others and retries once
246    /// (plan section 3.13).
247    ///
248    /// [`Registry::get`]: super::Registry::get
249    pub fn get_cab(&self, name: &RawStr, meter: &Arc<Meter>) -> Result<Option<Cab>, Error> {
250        Ok(self.get_cab_held(name, meter)?.map(|h| h.cab))
251    }
252
253    /// [`Self::get_cab`], with the handle that keeps a dependency's CAB's
254    /// container alive while the caller holds it ([`HeldCab`]): an eviction
255    /// drops only the LRU's handle, so the CAB's pointers into its sibling
256    /// entries keep resolving (rather than failing with
257    /// [`DerefError::ContainerDropped`]).
258    pub fn get_cab_held(
259        &self,
260        name: &RawStr,
261        meter: &Arc<Meter>,
262    ) -> Result<Option<HeldCab>, Error> {
263        self.room(|| self.inner.registry.get_held(name, meter))
264    }
265
266    /// `find_file(name, is_dependency)`: what UnityPy's returns
267    /// (`environment.py:310-354`), the file itself, of whatever kind. First
268    /// the CAB [`Self::get_cab`] finds, as the file it is (UnityPy's `cabs`
269    /// hold the file: `environment.py:252-264`): a `SerializedFile`, or a raw
270    /// reader, a bundle entry's being that entry
271    /// ([`crate::files::BundleFile::entry`]). Else the resolver's source for
272    /// `name` ([`CabResolver::find_file`]), loaded: a bundle, a
273    /// `SerializedFile`, a raw reader (a WebFile is refused in P1, as
274    /// [`Self::load`] refuses one). With [`EnvOptions::keep_resolver_loads`]
275    /// that load is a [`FileEntry`] under the resolved source's name, never
276    /// evicted, a dependency as `is_dependency` says (UnityPy's default is
277    /// true, and a dereference's call takes it): a dependency's objects are
278    /// in neither [`Self::objects`] nor [`Self::container`]. Without it
279    /// ([`EnvOptions::batch`]) the load is an evictable dependency in the
280    /// LRU only, whatever the flag, so it is in none of [`Self::files`],
281    /// `objects` or `container`, the one way this call differs from
282    /// UnityPy's there (`PARITY.md` section 19.3, "resolver loads under
283    /// `keep_resolver_loads` false"). `None` where the resolver answers
284    /// none (UnityPy's `None`); the resolver's error where it returns one
285    /// (UnityPy's walk's `FileNotFoundError`, [`CabResolver::find_file`]).
286    /// `meter` as for [`Self::get_cab`]. A pool refusal in the lookup, in
287    /// the resolver's answer (its own, counted as it returns) or in the
288    /// load evicts the others and retries that step once (plan section
289    /// 3.13; review round 12: the resolver's own refusal was returned
290    /// untried, which a dereference retried). A dependency's
291    /// `SerializedFile` may outlive its bundle in the LRU, as `get_cab`'s
292    /// may: [`Self::get_cab_held`] returns the handle that keeps it.
293    /// (Review round 11: a container the resolver loaded was `None`, the
294    /// answer a miss gives.)
295    ///
296    /// [`CabResolver::find_file`]: super::CabResolver::find_file
297    /// [`EnvOptions::keep_resolver_loads`]: super::EnvOptions::keep_resolver_loads
298    /// [`EnvOptions::batch`]: super::EnvOptions::batch
299    /// [`FileEntry`]: super::FileEntry
300    pub fn find_file(
301        &self,
302        name: &RawStr,
303        is_dependency: bool,
304        meter: &Arc<Meter>,
305    ) -> Result<Option<File>, Error> {
306        match self.find(name, is_dependency, meter, None)? {
307            None => Ok(None),
308            Some((Found::File(file), _)) => Ok(Some(file)),
309            Some((Found::Reused(object), _)) => Ok(Some(File::Serialized(object.file().clone()))),
310            // A raw entry the registry answered is in its bundle's cell, so
311            // `entry` reads the cell; it takes the retry all the same.
312            Some((Found::Cab(cab), _)) => self.room(|| cab_file(&cab)).map(Some),
313        }
314    }
315
316    /// [`Self::find_file`]'s lookup, and how it reached what it found. A
317    /// pool refusal in the registry's lookup, or one the resolver's
318    /// `find_file` returns, evicts the others and retries that step once;
319    /// the resolver's load takes its own (`load_resolved`), so a retry never
320    /// loads again what a load before it loaded (plan section 3.13; review
321    /// round 12: the resolver's refusal was retried inside a dereference
322    /// only, whose retry encloses this lookup).
323    fn find(
324        &self,
325        name: &RawStr,
326        is_dependency: bool,
327        meter: &Arc<Meter>,
328        mut work: Option<&mut HeldLookup<'_>>,
329    ) -> Result<Option<(Found, Reached)>, Error> {
330        // UnityPy environment.py:326-329: `get_cab(simplify_name(name))`,
331        // which simplifies again.
332        let found = self.room(|| -> Result<Option<Found>, Error> {
333            let simple = simplify_name(name, meter)?;
334            let registry = &self.inner.registry;
335            if let Some(work) = work.as_deref_mut() {
336                let Some(slot) = registry.slot(&simple, meter)? else {
337                    return Ok(None);
338                };
339                if let Some(object) = work.reused(|| FileOccurrence::in_slot(&slot))? {
340                    return Ok(Some(Found::Reused(object)));
341                }
342                Ok(registry.resolve_held(&slot)?.map(|held| {
343                    work.container = held.hold;
344                    Found::Cab(held.cab)
345                }))
346            } else {
347                Ok(registry.get(&simple, meter)?.map(Found::Cab))
348            }
349        })?;
350        if let Some(found) = found {
351            return Ok(Some((found, Reached::Lookup)));
352        }
353        // :330-354: the resolver stands for the walk of `env.path`. What it
354        // returns is the caller's code's, a pool refusal in it counted as it
355        // enters the core (`from_callers`) and retried as the core's own.
356        let Some(resolver) = self.inner.options.resolver.clone() else {
357            return Ok(None);
358        };
359        let Some(source) = self.room(|| from_callers(resolver.find_file(name.as_bytes())))? else {
360            return Ok(None);
361        };
362        let file = self.load_resolved(&source, Asked::Find { is_dependency })?;
363        Ok(Some((Found::File(file), Reached::Load)))
364    }
365
366    /// `PPtr.deref` from an object in `from` (`classes/PPtr.py:43-90`), by
367    /// the rules of [`pptr`]: `from`'s container is its bundle
368    /// ([`crate::files::ParentKind::Bundle`]'s handle), or, for a file loaded
369    /// at top level, this Environment, whose [`Self::files`] keys the sibling
370    /// scan compares. `from` need not have been loaded here (a batch job's
371    /// own bundle handle): its bundle siblings come from its parent, every
372    /// other CAB from this Environment. When `from`'s bundle has been
373    /// dropped (its weak handle no longer upgrades) the dereference fails
374    /// with [`DerefError::ContainerDropped`] rather than guess: UnityPy
375    /// cannot reach that state, since an object keeps its file's parent
376    /// alive, so the bindings and a batch engine keep a strong bundle handle
377    /// beside every `SerializedFile` they hand out. A pool refusal anywhere
378    /// in the dereference (reading or looking up from a dependency's file)
379    /// evicts the others and retries once, `from`'s top-level bundle held
380    /// meanwhile (plan section 3.13; review round 8: it had no retry).
381    pub fn deref(&self, from: &Arc<SerializedFile>, pptr: PPtr) -> Result<ObjectRef, DerefError> {
382        self.deref_inner(from, pptr, None)
383    }
384
385    /// Resolve as in [`Self::deref`], retaining the target's top-level
386    /// container when available. Hold the returned file to preserve access
387    /// to the target's siblings across dependency cache evictions.
388    ///
389    /// Charge the caller's work meter for the external path and each sibling
390    /// name examined, including any scan on retry.
391    pub fn deref_held(
392        &self,
393        from: &Arc<SerializedFile>,
394        pptr: PPtr,
395        meter: &Meter,
396    ) -> Result<(ObjectRef, Option<File>), DerefError> {
397        let mut work = HeldLookup {
398            meter,
399            container: None,
400            reuse: None,
401        };
402        let object = self.deref_inner(from, pptr, Some(&mut work))?;
403        Ok((object, work.container))
404    }
405
406    /// Resolve as in [`Self::deref_held`]. Before opening a known target,
407    /// offer its file occurrence to `reuse`. The callback may return a
408    /// retained object at the requested path ID in that occurrence. A hit
409    /// needs no new target container hold, even after a dependency eviction.
410    ///
411    /// Reuse assumes a dependency's source stays stable across reopens.
412    /// A resolver alias may load another copy of a dependency.
413    pub fn deref_held_reusing(
414        &self,
415        from: &Arc<SerializedFile>,
416        pptr: PPtr,
417        meter: &Meter,
418        mut reuse: impl FnMut(FileOccurrence) -> Result<Option<ObjectRef>, Error>,
419    ) -> Result<(ObjectRef, Option<File>), DerefError> {
420        let mut work = HeldLookup {
421            meter,
422            container: None,
423            reuse: Some(&mut reuse),
424        };
425        let object = self.deref_inner(from, pptr, Some(&mut work))?;
426        Ok((object, work.container))
427    }
428
429    fn deref_inner(
430        &self,
431        from: &Arc<SerializedFile>,
432        pptr: PPtr,
433        mut work: Option<&mut HeldLookup<'_>>,
434    ) -> Result<ObjectRef, DerefError> {
435        // UnityPy classes/PPtr.py:49-50
436        if pptr.path_id == 0 {
437            return Err(DerefError::Null);
438        }
439        // :53-54
440        if pptr.file_id == 0 {
441            if let Some(work) = work {
442                if let Some(object) = work.reused(|| Some(FileOccurrence::of(from)))? {
443                    return Ok(object);
444                }
445                work.container = top_container(from);
446            }
447            return object_in(from, pptr.path_id);
448        }
449        let _top = top_container(from);
450        // Nothing after a resolver's load charges anything, so a retry never
451        // loads again what the first run loaded.
452        self.room(|| {
453            self.reach_chain(from)?;
454            let (target, _) = self.external(from, pptr.file_id, None, work.as_deref_mut())?;
455            if let Found::Reused(object) = target {
456                return Ok(object);
457            }
458            let object = Self::object_of(&target, pptr.path_id)?;
459            if let Some(work) = work.as_deref_mut()
460                && work.container.is_none()
461            {
462                work.container = top_container(object.file());
463            }
464            Ok(object)
465        })
466    }
467
468    /// The file `from`'s external `file_id` names (`classes/PPtr.py:57-85`):
469    /// a sibling in `from`'s container (the bundle's `files`, or for a
470    /// top-level file this Environment's), else `find_file`; and how it was
471    /// reached ([`Reached`]). `siblings` is a container pass's index of
472    /// bundle names; without it the bundle's names are scanned.
473    pub(super) fn external(
474        &self,
475        from: &Arc<SerializedFile>,
476        file_id: i32,
477        siblings: Option<&mut Siblings>,
478        mut work: Option<&mut HeldLookup<'_>>,
479    ) -> Result<(Found, Reached), DerefError> {
480        let meter = from.meter();
481        let meter_work = work.as_ref().map(|work| work.meter);
482        let (external, clean) = external_name(from, file_id, meter_work)?;
483        // :63-78: the container's `files`, each key lower-cased, the first
484        // equal one wins.
485        let sibling = if let Some((parent, i)) = sibling_entry(from, &clean, siblings, meter_work)?
486        {
487            if let Some(work) = work.as_deref_mut()
488                && let Some(object) =
489                    work.reused(|| FileOccurrence::in_sibling(from, &parent, i))?
490            {
491                return Ok((Found::Reused(object), Reached::Sibling));
492            }
493            let file = parent.container_entry(i)?;
494            // Named as a sibling, a nested container is reached as a get
495            // of its name would reach it.
496            if matches!(file, File::Bundle(_) | File::Web(_))
497                && let File::Bundle(bundle) = parent
498            {
499                self.reach_sibling(from, &bundle, i, &file)?;
500            }
501            Some((file, Reached::Sibling))
502        } else if from.parent().is_none() {
503            match self.files_match(&clean) {
504                Some(FileMatch::File(f)) => {
505                    if let (File::Serialized(file), Some(work)) = (&f, work.as_deref_mut())
506                        && let Some(object) = work.reused(|| Some(FileOccurrence::of(file)))?
507                    {
508                        return Ok((Found::Reused(object), Reached::Lookup));
509                    }
510                    Some((f, Reached::Lookup))
511                }
512                // A matching key breaks the loop even when its value is
513                // None; only an absent key runs the for-else fallback
514                // (classes/PPtr.py:75-88).
515                Some(FileMatch::ZipNone) => {
516                    return Err(DerefError::NotFound {
517                        path: external.path.clone(),
518                    });
519                }
520                None => None,
521            }
522        } else {
523            None
524        };
525        match sibling {
526            Some((f, reached)) => Ok((Found::File(f), reached)),
527            // :80-85: `find_file`'s `None`, and its walk's
528            // `FileNotFoundError`, are the pointer's `FileNotFoundError`.
529            None => match self.find(&clean, true, meter, work) {
530                Ok(Some(t)) => Ok(t),
531                Ok(None) | Err(Error::NotFound(NotFound::Cab(_))) => Err(DerefError::NotFound {
532                    path: external.path.clone(),
533                }),
534                Err(e) => Err(e.into()),
535            },
536        }
537    }
538
539    /// The object holding `path_id` in what a dereference reached
540    /// (`classes/PPtr.py:90`, `assetsfile_dst.objects[m_PathID]`).
541    pub(super) fn object_of(target: &Found, path_id: i64) -> Result<ObjectRef, DerefError> {
542        match target.clone() {
543            Found::Reused(object) => Ok(object),
544            Found::Cab(Cab::Serialized(sf)) | Found::File(File::Serialized(sf)) => {
545                object_in(&sf, path_id)
546            }
547            Found::Cab(Cab::Raw(RawCab::InBundle { bundle, dir_index })) => {
548                Err(DerefError::RawTarget {
549                    name: bundle
550                        .directory()
551                        .get(dir_index)
552                        .map(|d| d.path.clone())
553                        .unwrap_or_default(),
554                })
555            }
556            Found::Cab(Cab::Raw(RawCab::File(raw))) | Found::File(File::Raw(raw)) => {
557                Err(DerefError::RawTarget {
558                    name: raw.name.clone(),
559                })
560            }
561            Found::File(File::Bundle(b)) => Err(DerefError::RawTarget {
562                name: b.name().clone(),
563            }),
564            Found::File(File::Web(w)) => Err(DerefError::RawTarget {
565                name: w.name().clone(),
566            }),
567        }
568    }
569}