Skip to main content

eq_network/
assets.rs

1use anyhow::{ensure, Context, Result};
2use serde::{Deserialize, Serialize};
3use std::{
4    collections::{BTreeMap, BTreeSet},
5    fs,
6    io::Read,
7    path::{Path, PathBuf},
8};
9
10/// Measured CRC-32 and size for one client file.
11#[derive(Debug, Serialize, Deserialize)]
12pub struct FileChecksum {
13    /// CRC-32 expected by server-side file validation.
14    pub crc32: u32,
15    /// File length in bytes.
16    pub size: u64,
17}
18
19/// Checksum inventory for one patched client installation.
20#[derive(Debug, Serialize, Deserialize)]
21pub struct Assets {
22    /// Human-readable client profile represented by the inventory.
23    pub client: String,
24    /// Case-normalized filename to measured checksum, or `None` when explicitly unknown.
25    pub files: BTreeMap<String, Option<FileChecksum>>,
26}
27
28/// A manifest response and the unscanned filenames that received checksum zero.
29#[derive(Debug, Eq, PartialEq)]
30pub struct FileResponse {
31    /// Encoded manifest hash and per-file CRC values.
32    pub body: Vec<u8>,
33    /// Requested filenames that were absent from the inventory.
34    pub unknown_files: Vec<String>,
35}
36
37impl Assets {
38    /// Load the checksum inventory compiled into the library without filesystem access.
39    ///
40    /// # Errors
41    ///
42    /// Returns an error if the bundled inventory cannot be decoded.
43    pub fn bundled() -> Result<Self> {
44        serde_json::from_slice(include_bytes!("../assets.json"))
45            .context("parse built-in asset inventory")
46    }
47
48    /// Inventory installed validation files, zone/model archives, and zone lists.
49    ///
50    /// # Errors
51    ///
52    /// Returns an error when the installation cannot be read or a discovered
53    /// inventory entry is invalid.
54    pub fn scan_all(directory: &Path) -> Result<Self> {
55        let mut names: BTreeSet<String> = include_str!("../protocol/p99-v62-files.txt")
56            .lines()
57            .map(str::to_ascii_lowercase)
58            .collect();
59        for (name, path) in directory_entries(directory)? {
60            if path.is_file()
61                && [".s3d", ".eqg", "_chr.txt", "_assets.txt"]
62                    .iter()
63                    .any(|suffix| name.ends_with(suffix))
64            {
65                names.insert(name);
66            }
67        }
68        Self::scan(directory, &names.into_iter().collect::<Vec<_>>())
69    }
70
71    /// Measure requested files in the installation, omitting files that are absent.
72    ///
73    /// # Errors
74    ///
75    /// Returns an error when a requested name is unsafe or a present file cannot
76    /// be read.
77    pub fn scan(directory: &Path, names: &[String]) -> Result<Self> {
78        let installed = directory_entries(directory)?;
79        let resources = if names
80            .iter()
81            .any(|name| name.eq_ignore_ascii_case("GlobalLoad.txt"))
82        {
83            installed
84                .get("resources")
85                .map(|path| directory_entries(path))
86                .transpose()?
87        } else {
88            None
89        };
90        let mut files = BTreeMap::new();
91        for name in names {
92            ensure!(
93                valid_asset_name(name),
94                "asset inventory entries must be filenames"
95            );
96            let name = name.to_ascii_lowercase();
97            let path = if name == "globalload.txt" {
98                resources.as_ref().and_then(|files| files.get(&name))
99            } else {
100                installed.get(&name)
101            };
102            let Some(path) = path else {
103                continue;
104            };
105            let mut file = fs::File::open(path)?;
106            let size = file.metadata()?.len();
107            let mut buffer = vec![0; 65536];
108            let mut crc = crc32fast::Hasher::new();
109            loop {
110                let count = file.read(&mut buffer)?;
111                if count == 0 {
112                    break;
113                }
114                crc.update(&buffer[..count]);
115            }
116            files.insert(
117                name,
118                Some(FileChecksum {
119                    crc32: crc.finalize(),
120                    size,
121                }),
122            );
123        }
124        Ok(Self {
125            client: "Titanium/P99-V62".into(),
126            files,
127        })
128    }
129
130    /// Build the checksum response requested by a world or zone manifest.
131    /// Unknown files receive zero and are returned for caller diagnostics;
132    /// the server decides whether that response is sufficient for admission.
133    ///
134    /// # Errors
135    ///
136    /// Returns an error when the manifest is malformed.
137    pub fn file_response(&self, manifest: &[u8]) -> Result<FileResponse> {
138        let mut output = crc32fast::hash(manifest).to_le_bytes().to_vec();
139        let mut unknown_files = Vec::new();
140        for entry in parse_manifest(manifest)? {
141            if entry.is_skipped() {
142                continue;
143            }
144            let crc = match self.files.get(&entry.name.to_ascii_lowercase()) {
145                Some(Some(checksum)) => checksum.crc32,
146                Some(None) => 0,
147                None => {
148                    unknown_files.push(entry.name);
149                    0
150                }
151            };
152            output.extend_from_slice(&entry.id.to_le_bytes());
153            output.extend_from_slice(&crc.to_le_bytes());
154        }
155        Ok(FileResponse {
156            body: output,
157            unknown_files,
158        })
159    }
160
161    /// Return the spell-file metadata used by the V62 CRC1 response.
162    ///
163    /// # Errors
164    ///
165    /// Returns an error when the inventory has no measured spell file.
166    pub fn spells(&self) -> Result<&FileChecksum> {
167        self.files
168            .get("spells_us.txt")
169            .and_then(Option::as_ref)
170            .context("spells_us.txt missing from asset inventory")
171    }
172}
173
174/// Index filenames once so a full installation scan does not repeatedly list it.
175fn directory_entries(directory: &Path) -> Result<BTreeMap<String, PathBuf>> {
176    let mut entries = BTreeMap::new();
177    for entry in fs::read_dir(directory)? {
178        let entry = entry?;
179        let name = entry.file_name().to_string_lossy().to_ascii_lowercase();
180        ensure!(
181            entries.insert(name, entry.path()).is_none(),
182            "ambiguous case-insensitive filename in asset directory"
183        );
184    }
185    Ok(entries)
186}
187
188fn valid_asset_name(name: &str) -> bool {
189    !name.is_empty()
190        && name.len() <= 200
191        && name
192            .bytes()
193            .all(|b| b.is_ascii_alphanumeric() || b == b'.' || b == b'_')
194        && name != "."
195        && name != ".."
196}
197
198/// One validated request from a V62 file manifest.
199#[derive(Debug, Eq, PartialEq)]
200pub struct ManifestEntry {
201    /// Server-provided identifier echoed in the response.
202    pub id: u16,
203    /// Manifest behavior flags.
204    pub flags: u8,
205    /// Validated filename without path components.
206    pub name: String,
207}
208
209impl ManifestEntry {
210    const fn is_skipped(&self) -> bool {
211        self.flags == 2
212    }
213}
214
215/// Parse and validate a V62 file manifest without accepting path components.
216///
217/// # Errors
218///
219/// Returns an error for truncated entries, unsafe filenames, unsupported flags,
220/// duplicate identifiers, or an empty manifest.
221pub fn parse_manifest(mut bytes: &[u8]) -> Result<Vec<ManifestEntry>> {
222    let mut entries = Vec::new();
223    while !bytes.is_empty() {
224        ensure!(bytes.len() >= 4, "truncated file manifest");
225        let id = u16::from_le_bytes([bytes[0], bytes[1]]);
226        let flags = bytes[2];
227        ensure!(
228            matches!(flags, 1 | 2 | 5 | 9),
229            "unsupported file manifest flags"
230        );
231        let end = bytes[3..]
232            .iter()
233            .position(|&b| b == 0)
234            .context("unterminated manifest filename")?
235            + 3;
236        let name = std::str::from_utf8(&bytes[3..end])?;
237        ensure!(
238            !name.is_empty()
239                && name.len() <= 200
240                && name
241                    .bytes()
242                    .all(|b| b.is_ascii_alphanumeric() || b == b'.' || b == b'_'),
243            "invalid manifest filename"
244        );
245        ensure!(
246            !entries.iter().any(|entry: &ManifestEntry| entry.id == id),
247            "duplicate manifest ID"
248        );
249        entries.push(ManifestEntry {
250            id,
251            flags,
252            name: name.to_owned(),
253        });
254        bytes = &bytes[end + 1..];
255    }
256    ensure!(!entries.is_empty(), "empty file manifest");
257    Ok(entries)
258}
259
260#[cfg(test)]
261mod tests {
262    use super::*;
263
264    struct Installation(PathBuf);
265
266    impl Installation {
267        fn new() -> Self {
268            let path =
269                std::env::temp_dir().join(format!("p99-assets-{:016x}", rand::random::<u64>()));
270            fs::create_dir(&path).unwrap();
271            Self(path)
272        }
273
274        fn write(&self, name: &str, body: &[u8]) {
275            let path = self.0.join(name);
276            fs::create_dir_all(path.parent().unwrap()).unwrap();
277            fs::write(path, body).unwrap();
278        }
279    }
280
281    impl Drop for Installation {
282        fn drop(&mut self) {
283            let _ = fs::remove_dir_all(&self.0);
284        }
285    }
286
287    fn manifest(entries: &[(u16, u8, &str)]) -> Vec<u8> {
288        let mut bytes = Vec::new();
289        for (id, flags, name) in entries {
290            bytes.extend_from_slice(&id.to_le_bytes());
291            bytes.push(*flags);
292            bytes.extend_from_slice(name.as_bytes());
293            bytes.push(0);
294        }
295        bytes
296    }
297
298    #[test]
299    fn discovers_measured_assets_without_absent_or_personal_files() {
300        let install = Installation::new();
301        install.write("NewZone.S3D", b"zone archive");
302        install.write("NewZone_chr.txt", b"2\nabc,missing_chr\ndef,present\n");
303        install.write("NewZone_assets.txt", b"missing_object.eqg\n");
304        install.write("Present.EQG", b"model archive");
305        install.write("AnotherZone.eqg", b"new format zone");
306        install.write("resources/GLOBALLOAD.TXT", b"global model list");
307        install.write("GlobalLoad.txt", b"incorrect root copy");
308        install.write("eqclient.ini", b"private settings");
309        install.write("eqlog_ExampleCharacter.txt", b"private messages");
310        install.write("notes.txt", b"private notes");
311
312        let assets = Assets::scan_all(&install.0).unwrap();
313        for (name, content) in [
314            ("newzone.s3d", b"zone archive".as_slice()),
315            ("present.eqg", b"model archive".as_slice()),
316            ("anotherzone.eqg", b"new format zone".as_slice()),
317            ("globalload.txt", b"global model list".as_slice()),
318        ] {
319            let file = assets.files[name].as_ref().unwrap();
320            assert_eq!(file.crc32, crc32fast::hash(content));
321            assert_eq!(file.size, content.len() as u64);
322        }
323        for name in [
324            "newzone_2_obj.s3d",
325            "newzone.eqg",
326            "anotherzone_chr.txt",
327            "missing_chr.s3d",
328            "missing_chr.eqg",
329            "missing_object.eqg",
330        ] {
331            assert!(!assets.files.contains_key(name), "{name}");
332        }
333        assert!(assets.files.values().all(Option::is_some));
334        assert!(assets.files.contains_key("newzone_chr.txt"));
335        assert!(assets.files.contains_key("newzone_assets.txt"));
336        for name in ["eqclient.ini", "eqlog_examplecharacter.txt", "notes.txt"] {
337            assert!(!assets.files.contains_key(name), "{name}");
338        }
339    }
340
341    #[test]
342    fn responds_only_to_requested_files_with_server_ids_and_manifest_order() {
343        let install = Installation::new();
344        install.write("FirstZone.s3d", b"first zone");
345        install.write("SecondZone.s3d", b"second zone");
346        let mut assets = Assets::scan_all(&install.0).unwrap();
347        // Older inventories may still explicitly mark absent files with null.
348        assets.files.insert("secondzone_assets.txt".into(), None);
349        let request = manifest(&[
350            (42, 1, "SECONDZONE.S3D"),
351            (8, 9, "secondzone_assets.txt"),
352            (99, 2, "unscanned_skipped_file.eqg"),
353        ]);
354        let mut expected = crc32fast::hash(&request).to_le_bytes().to_vec();
355        expected.extend_from_slice(&42_u16.to_le_bytes());
356        expected.extend_from_slice(&crc32fast::hash(b"second zone").to_le_bytes());
357        expected.extend_from_slice(&8_u16.to_le_bytes());
358        expected.extend_from_slice(&0_u32.to_le_bytes());
359        let response = assets.file_response(&request).unwrap();
360        assert_eq!(response.body, expected);
361        assert!(response.unknown_files.is_empty());
362        assets.files.remove("secondzone_assets.txt");
363        let response = assets.file_response(&request).unwrap();
364        assert_eq!(response.body, expected);
365        assert_eq!(response.unknown_files, ["secondzone_assets.txt"]);
366    }
367
368    #[test]
369    fn unknown_files_receive_zero_without_losing_known_checksums_or_inventory_state() {
370        let install = Installation::new();
371        install.write("Present.s3d", b"present");
372        let mut assets = Assets::scan(&install.0, &["present.s3d".into()]).unwrap();
373        assets.files.insert("absent.eqg".into(), None);
374        let request = manifest(&[
375            (17, 1, "UNKNOWN.EQG"),
376            (22, 5, "PRESENT.S3D"),
377            (9, 9, "absent.eqg"),
378            (31, 2, "skipped.eqg"),
379        ]);
380        let response = assets.file_response(&request).unwrap();
381        let mut expected = crc32fast::hash(&request).to_le_bytes().to_vec();
382        for (id, crc) in [(17u16, 0u32), (22, crc32fast::hash(b"present")), (9, 0)] {
383            expected.extend(id.to_le_bytes());
384            expected.extend(crc.to_le_bytes());
385        }
386        assert_eq!(response.body, expected);
387        assert_eq!(response.unknown_files, ["UNKNOWN.EQG"]);
388        assert_eq!(assets.files.len(), 2);
389        assert!(!assets.files.contains_key("unknown.eqg"));
390    }
391
392    #[test]
393    fn zero_fallback_still_rejects_malformed_manifests() {
394        let assets = Assets {
395            client: "test".into(),
396            files: BTreeMap::new(),
397        };
398        for invalid in [
399            vec![],
400            vec![1, 0, 1],
401            manifest(&[(1, 3, "unknown.eqg")]),
402            manifest(&[(1, 1, "../unknown.eqg")]),
403            manifest(&[(1, 1, "first.eqg"), (1, 1, "second.eqg")]),
404        ] {
405            assert!(assets.file_response(&invalid).is_err());
406        }
407    }
408
409    #[test]
410    fn explicit_scan_is_limited_to_requested_filenames() {
411        let install = Installation::new();
412        install.write("NewZone.s3d", b"zone");
413        install.write("OtherZone.s3d", b"other");
414        let assets =
415            Assets::scan(&install.0, &["newzone.s3d".into(), "missing.eqg".into()]).unwrap();
416        assert_eq!(assets.files.len(), 1);
417        assert!(assets.files["newzone.s3d"].is_some());
418        assert!(!assets.files.contains_key("missing.eqg"));
419        assert!(Assets::scan(&install.0, &["../outside.s3d".into()]).is_err());
420    }
421}