Skip to main content

unityrs_core/provider/
generator.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/TypeTreeGenerator.py. See THIRD_PARTY_LICENSES.
2//! External script schemas, not an IL2CPP/Mono generator. Callers decode their
3//! own `TypeTreeGeneratorAPI` or `Il2CppDumper` output, normalize its rows with
4//! [`generator_node_list`], compile during registration, and supply the trees.
5//! No dump, generated schema, or native generator is bundled with the library.
6
7use super::{ProviderError, TreeRequest, TypeTreeProvider};
8use crate::RawStr;
9use crate::limits::{ChargeError, Meter, MeteredVec};
10use crate::typetree::{NodeList, NodeRow, Tree, TreeError};
11use std::fmt;
12use std::sync::{Arc, Mutex};
13
14/// An external generator or dump reader, with trees compiled during registration.
15/// Failures retain their Python category through [`ProviderError::python_exception`].
16/// The callback is always called without a cache lock held.
17pub trait ScriptGenerator: Send + Sync + fmt::Debug {
18    /// Assembly has the case-sensitive `.dll` suffix; fullname is namespace.class
19    /// (or class alone). `None` models a generator miss.
20    fn get_nodes(
21        &self,
22        assembly: &RawStr,
23        fullname: &RawStr,
24    ) -> Result<Option<Arc<Tree>>, ProviderError>;
25}
26
27/// The node conversion of `get_nodes_up` (`helpers/TypeTreeGenerator.py:50-75`):
28/// size/version zero, meta flags retained, other optional fields absent.
29pub fn generator_node_list(mut rows: MeteredVec<NodeRow>) -> Result<NodeList, TreeError> {
30    let meter = rows.charge().meter().clone();
31    let mut bounds = crate::limits::TreeTraversal::new(&meter, u32::MAX);
32    for row in rows.as_mut_slice() {
33        bounds.step(0, 0, 1)?;
34        row.byte_size = 0;
35        row.version = 0;
36        row.type_flags = None;
37        row.variable_count = None;
38        row.index = None;
39        row.ref_type_hash = None;
40    }
41    // Linear linking/table construction below (including parent-stack pops).
42    meter.count_decode(
43        u64::try_from(rows.len())
44            .unwrap_or(u64::MAX)
45            .saturating_mul(8),
46    )?;
47    NodeList::from_rows(rows)
48}
49
50/// One externally compiled script schema. No input-sized copy is implicit.
51#[derive(Debug)]
52pub struct DumpEntry {
53    assembly: RawStr,
54    fullname: RawStr,
55    tree: Arc<Tree>,
56}
57
58impl DumpEntry {
59    /// API-style separate namespace and class fields.
60    pub fn api(
61        assembly: RawStr,
62        namespace: &RawStr,
63        class: RawStr,
64        tree: Arc<Tree>,
65        meter: &Arc<Meter>,
66    ) -> Result<Self, ChargeError> {
67        let fullname = if namespace.is_empty() {
68            class
69        } else {
70            copy_concat(&[namespace.as_bytes(), b".", class.as_bytes()], meter)?
71        };
72        Ok(Self::il2cpp(assembly, fullname, tree))
73    }
74
75    /// Il2CppDumper-style fully qualified type name and assembly name. The
76    /// caller supplies its decoded schema; native metadata extraction is external.
77    #[must_use]
78    pub fn il2cpp(assembly: RawStr, fullname: RawStr, tree: Arc<Tree>) -> Self {
79        Self {
80            assembly,
81            fullname,
82            tree,
83        }
84    }
85}
86
87/// A synthetic or caller-owned dump catalogue. First matching entry wins.
88#[derive(Debug)]
89pub struct DumpProvider {
90    entries: MeteredVec<DumpEntry>,
91}
92impl DumpProvider {
93    /// Take an already charged catalogue; no copy or allocation.
94    #[must_use]
95    pub fn new(entries: MeteredVec<DumpEntry>) -> Self {
96        Self { entries }
97    }
98}
99impl ScriptGenerator for DumpProvider {
100    fn get_nodes(
101        &self,
102        assembly: &RawStr,
103        fullname: &RawStr,
104    ) -> Result<Option<Arc<Tree>>, ProviderError> {
105        let meter = self.entries.charge().meter();
106        for e in self.entries.as_slice() {
107            if keys_match(meter, &e.assembly, &e.fullname, assembly, fullname)
108                .map_err(|e| refusal(e, Arc::from("script work refused")))?
109            {
110                return Ok(Some(e.tree.clone()));
111            }
112        }
113        Ok(None)
114    }
115}
116
117#[derive(Debug)]
118struct Cached {
119    assembly: RawStr,
120    fullname: RawStr,
121    tree: Arc<Tree>,
122}
123
124/// UnityPy's `get_nodes_up` lookup/cache wrapper, usable in a provider chain.
125/// Its entry bound only limits retention; it never changes an answer.
126#[derive(Debug)]
127pub struct GeneratorProvider<G> {
128    generator: G,
129    cache: Mutex<MeteredVec<Cached>>,
130    meter: Arc<Meter>,
131    max_entries: usize,
132    refusal_detail: Arc<str>,
133}
134const _: () = {
135    crate::send_sync::<dyn ScriptGenerator>();
136    crate::send_sync::<DumpEntry>();
137    crate::send_sync::<DumpProvider>();
138    crate::send_sync::<GeneratorProvider<DumpProvider>>();
139};
140impl<G: ScriptGenerator> GeneratorProvider<G> {
141    /// Create an empty, fallibly grown cache on `meter`.
142    #[must_use]
143    pub fn new(
144        generator: G,
145        meter: &Arc<Meter>,
146        max_entries: usize,
147        refusal_detail: Arc<str>,
148    ) -> Self {
149        Self {
150            generator,
151            cache: Mutex::new(MeteredVec::new(meter)),
152            meter: meter.clone(),
153            max_entries,
154            refusal_detail,
155        }
156    }
157
158    /// Answers retained under the original assembly/fullname pair.
159    #[must_use]
160    pub fn cached(&self) -> usize {
161        self.cache.lock().map_or(0, |c| c.len())
162    }
163
164    /// Case-sensitive suffix normalization and cache keys as UnityPy supplies
165    /// them (`helpers/TypeTreeGenerator.py:50-75`). The original assembly name
166    /// is the key: `Assembly` and `Assembly.dll` remain distinct entries.
167    pub fn get_nodes_up(
168        &self,
169        assembly: &RawStr,
170        fullname: &RawStr,
171    ) -> Result<Option<Arc<Tree>>, ProviderError> {
172        if let Ok(cache) = self.cache.lock() {
173            for c in cache.as_slice() {
174                if keys_match(&self.meter, &c.assembly, &c.fullname, assembly, fullname)
175                    .map_err(|e| self.memory(e))?
176                {
177                    return Ok(Some(c.tree.clone()));
178                }
179            }
180        }
181        let normalized;
182        self.meter
183            .count_decode(1 + u64::try_from(assembly.len().min(4)).unwrap_or(u64::MAX))
184            .map_err(|e| self.memory(e))?;
185        let lookup_assembly = if assembly.as_bytes().ends_with(b".dll") {
186            assembly
187        } else {
188            normalized = copy_concat(&[assembly.as_bytes(), b".dll"], &self.meter)
189                .map_err(|e| self.memory(e))?;
190            &normalized
191        };
192        let answer = self.generator.get_nodes(lookup_assembly, fullname)?;
193        if let Some(tree) = &answer
194            && let Ok(mut cache) = self.cache.lock()
195            && cache.len() < self.max_entries
196        {
197            for c in cache.as_slice() {
198                if keys_match(&self.meter, &c.assembly, &c.fullname, assembly, fullname)
199                    .map_err(|e| self.memory(e))?
200                {
201                    return Ok(answer);
202                }
203            }
204            let assembly =
205                copy_concat(&[assembly.as_bytes()], &self.meter).map_err(|e| self.memory(e))?;
206            let fullname =
207                copy_concat(&[fullname.as_bytes()], &self.meter).map_err(|e| self.memory(e))?;
208            cache
209                .push(Cached {
210                    assembly,
211                    fullname,
212                    tree: tree.clone(),
213                })
214                .map_err(|e| self.memory(e))?;
215        }
216        Ok(answer)
217    }
218
219    fn memory(&self, error: ChargeError) -> ProviderError {
220        refusal(error, self.refusal_detail.clone())
221    }
222}
223impl<G: ScriptGenerator> TypeTreeProvider for GeneratorProvider<G> {
224    fn name(&self) -> &'static str {
225        "script"
226    }
227    fn accepts_scripts(&self) -> bool {
228        true
229    }
230    fn tree(&self, req: &TreeRequest<'_>) -> Result<Option<Arc<Tree>>, ProviderError> {
231        let Some(script) = req.script else {
232            return Ok(None);
233        };
234        let joined;
235        let fullname = if script.namespace.is_empty() {
236            &script.class
237        } else {
238            joined = copy_concat(
239                &[script.namespace.as_bytes(), b".", script.class.as_bytes()],
240                &self.meter,
241            )
242            .map_err(|e| self.memory(e))?;
243            &joined
244        };
245        self.get_nodes_up(&script.assembly, fullname)
246    }
247}
248
249fn refusal(error: ChargeError, detail: Arc<str>) -> ProviderError {
250    let mut out = ProviderError::new("script", detail);
251    match error {
252        ChargeError::Limit(l) => out.limit = Some(l),
253        ChargeError::Budget(b) => out.memory = Some(b),
254        ChargeError::Allocator(a) => out.allocator = Some(a),
255    }
256    out
257}
258
259/// One step per comparison, plus an upper bound on the bytes it examines.
260fn same(meter: &Arc<Meter>, a: &RawStr, b: &RawStr) -> Result<bool, ChargeError> {
261    let bytes = if a.len() == b.len() { a.len() } else { 0 };
262    crate::limits::TreeTraversal::new(meter, u32::MAX).step(
263        0,
264        0,
265        1_u64.saturating_add(u64::try_from(bytes).unwrap_or(u64::MAX)),
266    )?;
267    Ok(a == b)
268}
269
270fn keys_match(
271    meter: &Arc<Meter>,
272    a: &RawStr,
273    f: &RawStr,
274    assembly: &RawStr,
275    fullname: &RawStr,
276) -> Result<bool, ChargeError> {
277    Ok(same(meter, a, assembly)? && same(meter, f, fullname)?)
278}
279
280fn copy_concat(parts: &[&[u8]], meter: &Arc<Meter>) -> Result<RawStr, ChargeError> {
281    let bytes = parts.iter().fold(0_u64, |sum, p| {
282        sum.saturating_add(u64::try_from(p.len()).unwrap_or(u64::MAX))
283    });
284    meter.count_decode(bytes)?;
285    RawStr::charged_concat(parts, meter)
286}