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}