Skip to main content
Verticopolis engine

verticopolis_engine/load/
container.rs

1//! The `.vctower` container: base64 and compression framing, the stamp, encode and decode.
2
3use super::*;
4
5/// The reason a `.vctower` is refused for inflating past the size cap.
6pub(crate) const EXPANDS_TOO_FAR: &str =
7    "this .vctower expands to more data than we will hold; it looks crafted rather than saved";
8
9/// Reads a `.vctower` file's text into its save JSON, ready for
10/// [`deserialize`]. Refuses text that is not a `.vctower` file, and one that
11/// would inflate past 32 MiB.
12pub fn decode_vctower(text: &str) -> Result<Value, String> {
13    parse_save_json(&inflate_vctower(text)?).map_err(|e| format!("json: {e}"))
14}
15
16/// [`decode_vctower`] for a file's bytes, which reads the binary file too: a
17/// `VCTOWER2` file (the stamp, a newline and the raw deflate bytes) is read
18/// as it is, and any other file as its UTF-8 text.
19pub fn decode_vctower_bytes(bytes: &[u8]) -> Result<Value, String> {
20    parse_save_json(&inflate_vctower_bytes(bytes)?).map_err(|e| format!("json: {e}"))
21}
22
23/// The save text inside a `.vctower` file of either kind, as
24/// [`decode_vctower_bytes`] parses it.
25pub(crate) fn inflate_vctower_bytes(bytes: &[u8]) -> Result<Vec<u8>, String> {
26    match binary_stamp(bytes) {
27        Some(after) => {
28            let packed = after
29                .strip_prefix(b"\n")
30                .ok_or("not a VCTOWER2 file: no newline after the stamp")?;
31            inflate_packed(packed).map_err(|e| match e {
32                InflateError::NotAContainer => "not a VCTOWER2 file".to_string(),
33                InflateError::ExpandsTooFar => EXPANDS_TOO_FAR.to_string(),
34                InflateError::Damaged(why) => why,
35            })
36        }
37        None => match std::str::from_utf8(bytes) {
38            Ok(text) => inflate_vctower(text),
39            Err(_) => Err("not a VCTOWER1 or VCTOWER2 file".to_string()),
40        },
41    }
42}
43
44/// What follows the `VCTOWER2` stamp of a binary file, or `None` when the
45/// bytes carry another stamp. `VCTOWER20` and the like name later versions,
46/// so the stamp counts only when no digit follows it.
47pub(crate) fn binary_stamp(bytes: &[u8]) -> Option<&[u8]> {
48    let after = bytes.strip_prefix(TOWER_FILE_MAGIC_BINARY.as_bytes())?;
49    (!after.first().is_some_and(u8::is_ascii_digit)).then_some(after)
50}
51
52/// Why the save text could not be taken out of a `.vctower` container.
53pub(crate) enum InflateError {
54    /// The text does not start with the `VCTOWER1` stamp.
55    NotAContainer,
56    /// The text inflates past the size cap.
57    ExpandsTooFar,
58    /// The packed data is not valid deflate.
59    Damaged(String),
60}
61
62/// The save text inside a VCTOWER1 container, as `decode_vctower` parses it.
63pub(crate) fn inflate_vctower(text: &str) -> Result<Vec<u8>, String> {
64    inflate_container(text).map_err(|e| match e {
65        InflateError::NotAContainer => "not a VCTOWER1 file".to_string(),
66        InflateError::ExpandsTooFar => EXPANDS_TOO_FAR.to_string(),
67        InflateError::Damaged(why) => why,
68    })
69}
70
71/// `inflate_vctower` with the reason as a variant, for a caller that words
72/// each refusal itself.
73pub(crate) fn inflate_container(text: &str) -> Result<Vec<u8>, InflateError> {
74    let trimmed = js_trim(text);
75    if !trimmed.starts_with(TOWER_FILE_MAGIC) {
76        return Err(InflateError::NotAContainer);
77    }
78    inflate_packed(&lenient_base64(&trimmed[TOWER_FILE_MAGIC.len()..]))
79}
80
81/// The save JSON inside a file's deflate bytes, capped at
82/// `MAX_SAVE_INFLATED_BYTES`: the payload of a `VCTOWER1` file once its
83/// base64 is read, or of a `VCTOWER2` file as it is.
84pub(crate) fn inflate_packed(packed: &[u8]) -> Result<Vec<u8>, InflateError> {
85    use std::io::Read;
86    let mut out = Vec::new();
87    flate2::read::DeflateDecoder::new(packed)
88        .take(MAX_SAVE_INFLATED_BYTES + 1)
89        .read_to_end(&mut out)
90        .map_err(|e| InflateError::Damaged(format!("inflate: {e}")))?;
91    if out.len() as u64 > MAX_SAVE_INFLATED_BYTES {
92        return Err(InflateError::ExpandsTooFar);
93    }
94    // `TextDecoder` drops a leading byte order mark before `JSON.parse` sees it.
95    if out.starts_with(b"\xEF\xBB\xBF") {
96        out.drain(..3);
97    }
98    Ok(out)
99}
100
101#[doc(hidden)]
102/// `JSON.parse` for save text that a JavaScript host wrote. A JavaScript
103/// string can hold half of a surrogate pair (a name cut at a UTF-16 length,
104/// for one), and `JSON.stringify` writes it as a `\udxxx` escape that
105/// `serde_json` refuses, since a Rust string cannot hold it. Each such escape
106/// becomes U+FFFD, the character `TextEncoder` substitutes for an unpaired
107/// surrogate, so the save
108/// loads with a replacement character where the half character was. Paired
109/// escapes, every other escape and every byte outside a string pass through
110/// unchanged; text with no lone surrogate escape is parsed as given.
111pub fn parse_save_json(text: &[u8]) -> Result<Value, serde_json::Error> {
112    match repair_lone_surrogates(text) {
113        Some(fixed) => serde_json::from_slice(&fixed),
114        None => serde_json::from_slice(text),
115    }
116}
117
118/// The value of the four hex digits at `at`, if they are four hex digits.
119pub(super) fn hex4(text: &[u8], at: usize) -> Option<u16> {
120    let digits = text.get(at..at + 4)?;
121    let s = std::str::from_utf8(digits).ok()?;
122    if !s.bytes().all(|b| b.is_ascii_hexdigit()) {
123        return None;
124    }
125    u16::from_str_radix(s, 16).ok()
126}
127
128/// The text with every lone surrogate escape inside a string rewritten to
129/// `\ufffd`, or `None` when there is none (the common case, which then
130/// costs one scan and no copy).
131pub(crate) fn repair_lone_surrogates(text: &[u8]) -> Option<Vec<u8>> {
132    let mut out: Option<Vec<u8>> = None;
133    let mut copied = 0;
134    let mut in_string = false;
135    let mut i = 0;
136    while i < text.len() {
137        let b = text[i];
138        if !in_string {
139            in_string = b == b'"';
140            i += 1;
141            continue;
142        }
143        match b {
144            b'"' => {
145                in_string = false;
146                i += 1;
147            }
148            b'\\' if text.get(i + 1) == Some(&b'u') => {
149                let Some(unit) = hex4(text, i + 2) else {
150                    // A malformed escape: leave it for the parser to refuse.
151                    i += 2;
152                    continue;
153                };
154                let paired_low = || {
155                    text.get(i + 6) == Some(&b'\\')
156                        && text.get(i + 7) == Some(&b'u')
157                        && hex4(text, i + 8).is_some_and(|u| (0xDC00..=0xDFFF).contains(&u))
158                };
159                if (0xD800..=0xDBFF).contains(&unit) && paired_low() {
160                    i += 12;
161                } else if (0xD800..=0xDFFF).contains(&unit) {
162                    let buf = out.get_or_insert_with(|| Vec::with_capacity(text.len()));
163                    buf.extend_from_slice(&text[copied..i]);
164                    buf.extend_from_slice(b"\\ufffd");
165                    i += 6;
166                    copied = i;
167                } else {
168                    i += 6;
169                }
170            }
171            // Any other escape is two bytes; skipping both keeps an escaped
172            // quote or backslash from being read as the end of the string.
173            b'\\' => i += 2,
174            _ => i += 1,
175        }
176    }
177    out.map(|mut buf| {
178        buf.extend_from_slice(&text[copied..]);
179        buf
180    })
181}
182
183/// The first line of every `.vctower` text file, naming the format and its
184/// version: the deflate bytes follow as one line of base64.
185pub const TOWER_FILE_MAGIC: &str = "VCTOWER1";
186
187/// The first line of a binary `.vctower` file: the raw deflate bytes follow
188/// the newline as they are, a quarter smaller than the base64 of
189/// [`TOWER_FILE_MAGIC`].
190pub const TOWER_FILE_MAGIC_BINARY: &str = "VCTOWER2";
191
192/// How a file frames its deflate bytes.
193#[derive(Clone, Copy, Debug, PartialEq, Eq)]
194pub(crate) enum Frame {
195    /// `VCTOWER1`, a newline, the base64, a newline.
196    Text,
197    /// `VCTOWER2`, a newline, the raw deflate bytes.
198    Binary,
199}
200
201/// Writes save JSON as `.vctower` file bytes, as given. To write a player's
202/// tower, stamp it first with [`stamp_save`], or use
203/// [`encode_simulation_vctower`], which does both: a save with no stamp loads
204/// as a founder's tower. Refuses a save larger than a loader accepts.
205pub fn encode_vctower(save: &Value) -> Result<Vec<u8>, String> {
206    pack_json(&crate::canonical::js_json(save))
207}
208
209/// The container around a save's JSON text: the size check, the deflate and
210/// the base64 framing of [`encode_vctower`], shared with the streamed writer
211/// (`export_stream`) so the two cannot frame differently.
212pub(crate) fn pack_json(json: &str) -> Result<Vec<u8>, String> {
213    pack_json_as(json, Frame::Text)
214}
215
216/// [`pack_json`] in either frame.
217pub(crate) fn pack_json_as(json: &str, frame: Frame) -> Result<Vec<u8>, String> {
218    if json.len() as u64 > MAX_SAVE_INFLATED_BYTES {
219        return Err(format!(
220            "This tower's save data is larger than {} MB, the most a save can hold.",
221            MAX_SAVE_INFLATED_BYTES / (1024 * 1024)
222        ));
223    }
224    let packed = crate::fflate::deflate_level1(json.as_bytes());
225    if frame == Frame::Binary {
226        let mut out = Vec::with_capacity(TOWER_FILE_MAGIC_BINARY.len() + 1 + packed.len());
227        out.extend_from_slice(TOWER_FILE_MAGIC_BINARY.as_bytes());
228        out.push(b'\n');
229        out.extend_from_slice(&packed);
230        return Ok(out);
231    }
232    let b64 = base64::engine::general_purpose::STANDARD.encode(packed);
233    let mut out = Vec::with_capacity(TOWER_FILE_MAGIC.len() + b64.len() + 2);
234    out.extend_from_slice(TOWER_FILE_MAGIC.as_bytes());
235    out.push(b'\n');
236    out.extend_from_slice(b64.as_bytes());
237    out.push(b'\n');
238    Ok(out)
239}
240
241/// Stamps save JSON with the app that wrote it and when, as the web game does
242/// before writing a file. `app_version` names your host and its version (it
243/// must not read as a build older than 2.0, which the web game takes for a
244/// founder's tower); `saved_at_ms` is the time in milliseconds since the Unix
245/// epoch. Refuses JSON that is not a tower.
246pub fn stamp_save(save: &mut Value, app_version: &str, saved_at_ms: f64) -> Result<(), String> {
247    let carries_founder = detect_founder(save);
248    let Value::Object(m) = save else {
249        return Err("not a tower save (the save is not an object)".into());
250    };
251    if !m.get("minutes").is_some_and(Value::is_number)
252        || !m.get("units").is_some_and(Value::is_array)
253    {
254        return Err("not a tower save (no numeric minutes or no units list)".into());
255    }
256    check_stamp(app_version, saved_at_ms)?;
257    if carries_founder {
258        m.insert("founder".into(), json!(true));
259    }
260    m.insert("savedAt".into(), json!(saved_at_ms));
261    m.insert("appVersion".into(), json!(app_version));
262    Ok(())
263}
264
265/// The two checks on a stamp's own values, which [`stamp_save`] runs after
266/// the tower's: the time and the build name.
267pub(crate) fn check_stamp(app_version: &str, saved_at_ms: f64) -> Result<(), String> {
268    if !(saved_at_ms.is_finite() && saved_at_ms.abs() <= 8.64e15) {
269        return Err(format!("savedAt {saved_at_ms} is not a time"));
270    }
271    if parse_int(app_version).is_some_and(|v| v < 2.0) {
272        return Err(format!(
273            "appVersion {app_version:?} reads as a build before 2.0, which marks the tower as a founder's"
274        ));
275    }
276    Ok(())
277}
278
279/// Writes a game as `.vctower` file bytes: [`Simulation::serialize`],
280/// [`stamp_save`] and [`encode_vctower`] in one call, without holding the
281/// whole save in memory at once. The engine has no clock or version of its
282/// own, so pass your host's name and version and the time in milliseconds
283/// since the Unix epoch.
284pub fn encode_simulation_vctower(
285    sim: &Simulation,
286    app_version: &str,
287    saved_at_ms: f64,
288) -> Result<Vec<u8>, String> {
289    crate::export_stream::encode_vctower_string(sim.save_text(), app_version, saved_at_ms)
290}
291
292/// [`encode_simulation_vctower`] as a binary `.vctower` file
293/// ([`TOWER_FILE_MAGIC_BINARY`]): the same stamped save and deflate bytes,
294/// without the base64, so the file is a quarter smaller. A build from before
295/// the binary file refuses it as a file from a newer version.
296pub fn encode_simulation_vctower_binary(
297    sim: &Simulation,
298    app_version: &str,
299    saved_at_ms: f64,
300) -> Result<Vec<u8>, String> {
301    crate::export_stream::encode_vctower_string_as(
302        sim.save_text(),
303        app_version,
304        saved_at_ms,
305        Frame::Binary,
306    )
307}
308
309/// `Buffer.from(b64, "base64")`: decoding stops at the first `=`, every
310/// character outside the alphabet (whitespace included) is skipped, the
311/// URL-safe alphabet is taken alongside the standard one, padding is
312/// optional, a dangling single symbol is dropped, and the last symbol's
313/// unused bits are ignored.
314pub(super) fn lenient_base64(text: &str) -> Vec<u8> {
315    let body = text.split('=').next().unwrap_or("");
316    let mut symbols: String = body
317        .chars()
318        .filter_map(|c| match c {
319            'A'..='Z' | 'a'..='z' | '0'..='9' | '+' | '/' => Some(c),
320            '-' => Some('+'),
321            '_' => Some('/'),
322            _ => None,
323        })
324        .collect();
325    if symbols.len() % 4 == 1 {
326        symbols.pop();
327    }
328    // With the alphabet filtered, the padding cut, the dangling symbol
329    // dropped and trailing bits allowed, no input is left that the decoder
330    // refuses; like `Buffer.from`, garbage simply inflates to garbage.
331    base64::engine::GeneralPurpose::new(
332        &base64::alphabet::STANDARD,
333        base64::engine::GeneralPurposeConfig::new()
334            .with_decode_padding_mode(base64::engine::DecodePaddingMode::RequireNone)
335            .with_decode_allow_trailing_bits(true),
336    )
337    .decode(symbols.as_bytes())
338    .unwrap_or_default()
339}
340
341#[doc(hidden)]
342/// `String.prototype.trim`: strips WhiteSpace and LineTerminator. Compared
343/// with Rust's `is_whitespace`, JavaScript also counts U+FEFF and does not
344/// count U+0085 (NEL).
345pub fn js_trim(s: &str) -> &str {
346    s.trim_matches(is_js_whitespace)
347}
348
349/// Whether JavaScript's `trim` strips the character (see `js_trim`).
350pub(crate) fn is_js_whitespace(c: char) -> bool {
351    (c.is_whitespace() && c != '\u{85}') || c == '\u{feff}'
352}