unityrs_core/version/mod.rs
1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/UnityVersion.py, UnityPy/files/BundleFile.py, UnityPy/files/SerializedFile.py. See THIRD_PARTY_LICENSES.
2//! Unity versions with UnityPy's semantics, and UnityPy's two version chains.
3//!
4//! `UnityVersion.from_str` (`helpers/UnityVersion.py:62-88`) matches
5//! `^(\d+)\.(\d+)\.(\d+)(.+?)?(\d+)?(.*)$` (`helpers/UnityVersion.py:7-10`)
6//! with Python `re` (DOTALL; `\d` is any Unicode `Nd` digit). The type is one
7//! character (the lazy group takes exactly the non-digit the greedy `build`
8//! group leaves), lower-cased: `a` 0, `b` 1,
9//! `c` 2, `f` 3, `p` 4, `x` 5, anything else 255, nothing at all `f`. The packed
10//! value is `major<<48 | minor<<32 | build<<16 | type<<8 | number`, a plain OR
11//! of unbounded integers, so wide fields spill (`docs/CANONICAL_DUMP.md` 4.2).
12//! Each group goes through Python 3.11's `int()`, which refuses a string of
13//! more than [`PY_INT_MAX_STR_DIGITS`] digits (`sys.get_int_max_str_digits()`,
14//! leading zeros and any `Nd` digit counted): `from_str` then raises
15//! `ValueError`, exactly as for a string that does not match, so both chains
16//! treat it as [`VersionError::NoMatch`] (the bundle chain falls back, the
17//! `SerializedFile` chain fails).
18//!
19//! Chain 1, the bundle (`files/BundleFile.py:523-536`): the engine string; when
20//! it does not parse or its 16-bit major is 0, the fallback; with no fallback,
21//! an error. It decides the flag set (`:113-121`) and the format-6 alignment
22//! (`:129-131`).
23//!
24//! Chain 2, the `SerializedFile` (`files/SerializedFile.py:351-360`): its own
25//! string (format 7 and up); when empty or `0.0.0`, the parent *bundle's*
26//! engine string (a `WebFile` parent does not count); when still empty or
27//! `0.0.0`, the fallback; then `from_str`, which fails on a string that does
28//! not match whatever the fallback holds.
29//!
30//! **No copy.** A version keeps the bytes it was parsed from ([`UnityVersion::raw`]),
31//! and a [`VersionError::NoMatch`] the string that did not match. Both chains
32//! and [`UnityVersion::parse`] take the string as the file's own
33//! [`RawStr`] (a slice of its buffer, or the parent bundle's engine string,
34//! or the policy's fallback) and keep a clone of it, a reference count: a
35//! version string can be up to 32,767 bytes (`read_string_to_null`'s
36//! window) and every parse of an entry keeps its own version, so a copy
37//! would be an uncharged allocation per parse. The one heap a version owns
38//! is a packed integer of 2^128 or more ([`UnityVersion::heap_bytes`]),
39//! which the chains charge, at [`heap_cost`], to the handle charge of the
40//! file that keeps the version before the limbs are allocated.
41//!
42//! **Work.** Every parse of an entry parses its version again (the
43//! `SerializedFile` chain may parse the parent bundle's engine string, which
44//! that parse did not read). So the chains count a parse's work on the
45//! input's meter, as its `DecodeWork` ([`crate::limits::Meter`]), each step
46//! before it runs: the bytes it scans, and [`LIMB_WORK`] for each limb a
47//! step multiplies or merges. A group's digits are taken 19 at a time, each
48//! chunk one multiply over the limbs the value holds so far, and each merge
49//! over the group's own (review round 6 found every step going through all
50//! 226 limbs of a fixed array, uncounted: about 12 limbs a digit, and 2,260
51//! for the ten bytes of `2022.3.0f1`, ten steps of 226). So a group below
52//! 2^128 costs at most three limbs a step, linear in the string (every
53//! version a real file holds); a group of `d` significant digits past that
54//! costs about `d * d / 730` limbs, quadratic as `CPython`'s own `int()` is,
55//! which is why Python caps a group at [`PY_INT_MAX_STR_DIGITS`]: at most
56//! about 6 limbs a digit, under 50 counted a byte of the string (`tests`,
57//! `a_versions_packing_counts_the_limbs_it_holds_as_the_inputs_work`). A
58//! refused step stops the parse, its scanned bytes counted.
59//! [`UnityVersion::parse`], for a caller's own string, counts nothing.
60//!
61//! Owner: package C. The Unicode `Nd` table ([`crate::tables::nd_digit`]) is
62//! generated from the oracle's Python 3.11 (`tools/gen/`, package A).
63
64use std::cmp::Ordering;
65use std::hash::{Hash, Hasher};
66use std::sync::Arc;
67
68use crate::error::Error;
69use crate::limits::{Charge, heap_cost};
70use crate::raw::RawStr;
71
72mod packed;
73mod parse;
74
75pub use packed::Packed;
76pub use parse::{LIMB_WORK, MAX_LIMBS};
77
78/// Python 3.11's `sys.get_int_max_str_digits()`: `int()` refuses a longer
79/// digit string, so a version group longer than this does not parse.
80pub const PY_INT_MAX_STR_DIGITS: usize = 4300;
81
82/// A parsed Unity version: the raw bytes and UnityPy's packed integer.
83#[derive(Clone, Debug)]
84pub struct UnityVersion {
85 raw: RawStr,
86 packed: Packed,
87}
88
89impl UnityVersion {
90 /// `UnityVersion.from_str` on the raw bytes. The pattern is applied to the
91 /// surrogate-escaped string Python sees, so invalid UTF-8 bytes match `.`
92 /// and never `\d`; a group of more than [`PY_INT_MAX_STR_DIGITS`] digits
93 /// is [`VersionError::NoMatch`] (module docs). The version, or the
94 /// `NoMatch`, keeps a clone of `raw` (no copy: module docs). Its work is
95 /// counted nowhere: this is for a caller's own string; an input's are
96 /// parsed by the chains, which count it (module docs, "Work").
97 pub fn parse(raw: &RawStr) -> Result<Self, VersionError> {
98 match parse::parse_packed(raw.as_bytes(), parse::Work::new(None)) {
99 Ok(Some(packed)) => Ok(Self {
100 raw: raw.clone(),
101 packed,
102 }),
103 // Uncounted and uncharged, the parse is never refused.
104 Ok(None) | Err(_) => Err(VersionError::NoMatch(raw.clone())),
105 }
106 }
107
108 /// [`Self::parse`] of an input's string, its work counted on `charge`'s
109 /// meter (the input's) before each step runs, and a packed integer of
110 /// 2^128 or more charged to `charge` before its limbs are allocated
111 /// (module docs, "Work"). The outer error is the meter's refusal
112 /// ([`crate::LimitKind::DecodeWork`], or the charge's).
113 pub(crate) fn parse_charged(
114 raw: &RawStr,
115 charge: &mut Charge,
116 ) -> Result<Result<Self, VersionError>, Error> {
117 Ok(
118 match parse::parse_packed(raw.as_bytes(), parse::Work::new(Some(charge)))? {
119 Some(packed) => Ok(Self {
120 raw: raw.clone(),
121 packed,
122 }),
123 None => Err(VersionError::NoMatch(raw.clone())),
124 },
125 )
126 }
127
128 /// `UnityVersion(int)`: a version from a packed integer, as a TPK stores
129 /// its versions (`helpers/Tpk.py:464`). It has no raw string (`raw()` is
130 /// empty). Implemented by the scaffold, so `unityrs-tpk` (package A) can
131 /// pick a TPK entry by core's ordering before package C lands.
132 #[must_use]
133 pub fn from_packed(packed: u64) -> Self {
134 Self {
135 raw: RawStr::default(),
136 packed: Packed::from_u128(u128::from(packed)),
137 }
138 }
139
140 /// The bytes it was parsed from.
141 pub fn raw(&self) -> &RawStr {
142 &self.raw
143 }
144
145 /// The packed integer, exactly.
146 pub fn packed(&self) -> &Packed {
147 &self.packed
148 }
149
150 /// The heap this version owns: a packed integer of 2^128 or more's
151 /// limbs. The raw string is a shared slice and owns none. Implemented
152 /// by the scaffold; the chains charge it, at [`heap_cost`], to the
153 /// handle of the file that keeps it.
154 #[must_use]
155 pub fn heap_bytes(&self) -> usize {
156 self.packed.heap_bytes()
157 }
158
159 /// What its heap is charged at: the limbs' block, at [`heap_cost`].
160 fn heap_charge(&self) -> u64 {
161 match self.heap_bytes() {
162 0 => 0,
163 n => heap_cost(u64::try_from(n).unwrap_or(u64::MAX)),
164 }
165 }
166
167 /// The packed value when it fits `u64` (TPK lookups compare these).
168 /// Implemented by the scaffold.
169 pub fn packed_u64(&self) -> Option<u64> {
170 self.packed.as_u128().and_then(|v| u64::try_from(v).ok())
171 }
172
173 /// `(major, minor, build, type, number)`, each cut to its slot (16, 16, 16,
174 /// 8 and 8 bits). A type byte other than 0-5 and 255 raises, as
175 /// `UnityVersionType(...)` does (`UnityVersion.py:41-42`, `:109-110`).
176 pub fn as_tuple(&self) -> Result<(u16, u16, u16, u8, u8), VersionError> {
177 // UnityPy helpers/UnityVersion.py:28-54, :109-110
178 let ty = u8::try_from(self.packed.bits(8, 8)).unwrap_or(u8::MAX);
179 if !(ty <= 5 || ty == 255) {
180 return Err(VersionError::TypeByte(ty));
181 }
182 let field = |shift: u32| u16::try_from(self.packed.bits(shift, 16)).unwrap_or(u16::MAX);
183 Ok((
184 field(48),
185 field(32),
186 field(16),
187 ty,
188 u8::try_from(self.packed.bits(0, 8)).unwrap_or(u8::MAX),
189 ))
190 }
191
192 /// The 16-bit major, as UnityPy's `major` property cuts it.
193 #[must_use]
194 pub fn major(&self) -> u16 {
195 // UnityPy helpers/UnityVersion.py:28-30
196 u16::try_from(self.packed.bits(48, 16)).unwrap_or(u16::MAX)
197 }
198
199 /// `self < other` as Python compares `as_tuple()` with a shorter tuple
200 /// (`version < (2020, 3, 34)`).
201 pub fn lt_tuple(&self, other: &[u16]) -> Result<bool, VersionError> {
202 // UnityPy helpers/UnityVersion.py:122-127: tuple order, a shorter
203 // tuple that is a prefix being the smaller.
204 let (major, minor, build, ty, number) = self.as_tuple()?;
205 let mine = [major, minor, build, u16::from(ty), u16::from(number)];
206 Ok(mine.as_slice() < other)
207 }
208}
209
210impl PartialEq for UnityVersion {
211 /// Equality is on the packed integer, as Python's `int` equality.
212 fn eq(&self, other: &Self) -> bool {
213 self.packed == other.packed
214 }
215}
216
217impl Eq for UnityVersion {}
218
219impl Hash for UnityVersion {
220 fn hash<H: Hasher>(&self, state: &mut H) {
221 self.packed.hash(state);
222 }
223}
224
225impl Ord for UnityVersion {
226 /// As Python compares the `int`s (`Tpk.py:472-481`'s `exactVersion >= version`).
227 fn cmp(&self, other: &Self) -> Ordering {
228 self.packed.cmp(&other.packed)
229 }
230}
231
232impl PartialOrd for UnityVersion {
233 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
234 Some(self.cmp(other))
235 }
236}
237
238/// Why a version is what it is.
239#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
240pub enum VersionSource {
241 /// The file's own string.
242 Own,
243 /// The parent bundle's engine string (chain 2 only).
244 ParentBundle,
245 /// `config.FALLBACK_UNITY_VERSION`.
246 Fallback,
247 /// An opt-in override, never silent: reported in the API, the batch
248 /// manifest and the dump's `producer`.
249 Forced,
250}
251
252/// A chain's result.
253#[derive(Clone, Debug, PartialEq, Eq)]
254pub struct ResolvedVersion {
255 /// The version.
256 pub version: UnityVersion,
257 /// Where it came from.
258 pub source: VersionSource,
259}
260
261/// The fallback and the overrides.
262#[derive(Clone, Debug, Default)]
263#[non_exhaustive]
264pub struct VersionPolicy {
265 /// UnityPy's `config.FALLBACK_UNITY_VERSION`, as a string (UnityPy parses it
266 /// each time it is used; a bad string fails there). `None` raises where
267 /// UnityPy raises (`config.py:25-32`); the oracle leaves it unset.
268 pub fallback: Option<RawStr>,
269 /// Shared warning filter/emitter for `config.get_fallback_version`.
270 /// Bindings install their Python warning emitter; native callers may opt
271 /// into collecting warnings. Called before parsing the fallback string.
272 pub fallback_warnings: Option<Arc<dyn crate::config::FallbackWarningSink>>,
273 /// Replaces chain 1's result.
274 pub force_bundle: Option<UnityVersion>,
275 /// Replaces chain 2's result.
276 pub force_serialized: Option<UnityVersion>,
277}
278
279/// UnityPy's choice between `ArchiveFlags` and `ArchiveFlagsOld`.
280#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
281pub enum FlagsClass {
282 /// `ArchiveFlags`.
283 New,
284 /// `ArchiveFlagsOld`.
285 Old,
286}
287
288/// Version failures.
289#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
290#[non_exhaustive]
291pub enum VersionError {
292 /// The string does not match the pattern.
293 #[error("invalid version string {0}")]
294 NoMatch(RawStr),
295 /// A type byte outside 0-5 and 255 in a comparison.
296 #[error("invalid version type byte {0}")]
297 TypeByte(u8),
298 /// No usable version and no fallback set.
299 #[error(
300 "No valid Unity version found, and the fallback version is not correctly configured. Please explicitly set the value of UnityPy.config.FALLBACK_UNITY_VERSION."
301 )]
302 NoFallback,
303}
304
305/// Chain 1: `BundleFile.parse_version`. `engine` is the header's
306/// `version_engine`, kept by the result without a copy (module docs). Each
307/// parse's work is counted on `charge`'s meter, the input's, and the
308/// result's heap is charged to `charge`, the handle charge of the bundle
309/// that keeps it, before it is allocated (module docs, "Work"): the error
310/// is a [`VersionError`] or such a refusal.
311pub fn resolve_bundle(
312 engine: &RawStr,
313 policy: &VersionPolicy,
314 charge: &mut Charge,
315) -> Result<ResolvedVersion, Error> {
316 if let Some(v) = &policy.force_bundle {
317 return forced(v, charge);
318 }
319 // UnityPy files/BundleFile.py:523-536: a string that does not parse, or
320 // whose 16-bit major is 0, takes the fallback.
321 match UnityVersion::parse_charged(engine, charge)? {
322 Ok(version) if version.major() != 0 => {
323 return Ok(ResolvedVersion {
324 version,
325 source: VersionSource::Own,
326 });
327 }
328 Ok(dropped) => charge.release(dropped.heap_charge()),
329 Err(_) => {}
330 }
331 fallback(policy, charge, true)
332}
333
334/// A forced version, its heap charged before the copy.
335fn forced(v: &UnityVersion, charge: &mut Charge) -> Result<ResolvedVersion, Error> {
336 charge.grow(v.heap_charge())?;
337 Ok(ResolvedVersion {
338 version: v.clone(),
339 source: VersionSource::Forced,
340 })
341}
342
343/// `UnityVersion.from_str(config.get_fallback_version())` (`config.py:25-32`):
344/// no fallback raises; a fallback that does not match raises too.
345fn fallback(
346 policy: &VersionPolicy,
347 charge: &mut Charge,
348 bundle: bool,
349) -> Result<ResolvedVersion, Error> {
350 let s = policy.fallback.as_ref().ok_or(VersionError::NoFallback)?;
351 let s = policy.fallback_warnings.as_ref().map_or_else(
352 || Ok(s.clone()),
353 |warnings| warnings.warn_value_at(s, bundle),
354 )?;
355 Ok(ResolvedVersion {
356 version: UnityVersion::parse_charged(&s, charge)??,
357 source: VersionSource::Fallback,
358 })
359}
360
361/// `not s or s == "0.0.0"` (`SerializedFile.py:353`, `:358`).
362fn unusable(s: &RawStr) -> bool {
363 s.is_empty() || s.as_bytes() == b"0.0.0"
364}
365
366/// Chain 2: `SerializedFile.set_version`. `own` is the file's string (format
367/// 7 and up); `parent_engine` is `Some` only when the parent is a bundle
368/// (its header's `version_engine`). The string the chain picks is kept by
369/// the result without a copy (module docs). The parse's work and the
370/// result's heap go to `charge`, as [`resolve_bundle`]'s do.
371pub fn resolve_serialized(
372 own: &RawStr,
373 parent_engine: Option<&RawStr>,
374 policy: &VersionPolicy,
375 charge: &mut Charge,
376) -> Result<ResolvedVersion, Error> {
377 if let Some(v) = &policy.force_serialized {
378 return forced(v, charge);
379 }
380 // UnityPy files/SerializedFile.py:351-360
381 let (mut s, mut source) = (own, VersionSource::Own);
382 if unusable(s) {
383 if let Some(parent) = parent_engine {
384 (s, source) = (parent, VersionSource::ParentBundle);
385 }
386 if unusable(s) {
387 return fallback(policy, charge, false);
388 }
389 }
390 Ok(ResolvedVersion {
391 version: UnityVersion::parse_charged(s, charge)??,
392 source,
393 })
394}
395
396/// `files/BundleFile.py:113-121`: `ArchiveFlagsOld` below 2020, and below 2020.3.34,
397/// 2021.3.2 and 2022.1.1 on those lines.
398pub fn flags_class(engine: &UnityVersion) -> Result<FlagsClass, VersionError> {
399 // UnityPy files/BundleFile.py:113-121; `version[0]` is `as_tuple()[0]`,
400 // which raises as the comparison before it does.
401 let v = engine;
402 let major = v.as_tuple()?.0;
403 let old = v.lt_tuple(&[2020])?
404 || (major == 2020 && v.lt_tuple(&[2020, 3, 34])?)
405 || (major == 2021 && v.lt_tuple(&[2021, 3, 2])?)
406 || (major == 2022 && v.lt_tuple(&[2022, 1, 1])?);
407 Ok(if old {
408 FlagsClass::Old
409 } else {
410 FlagsClass::New
411 })
412}
413
414/// `files/BundleFile.py:129-131`: the 16-byte alignment after the header applies at
415/// format 7 and up, or with a 2019 engine at 2019.4.15 or later.
416pub fn uses_block_alignment(format: u32, engine: &UnityVersion) -> Result<bool, VersionError> {
417 // UnityPy files/BundleFile.py:129: `or` short-circuits, so from format 7
418 // the version is never compared.
419 if format >= 7 {
420 return Ok(true);
421 }
422 Ok(engine.as_tuple()?.0 == 2019 && !engine.lt_tuple(&[2019, 4, 15])?)
423}
424
425#[cfg(test)]
426mod tests;