Skip to main content

dayzmake_core/
pbo.rs

1use std::collections::{HashMap, HashSet};
2use std::ffi::OsStr;
3use std::fs::{File, create_dir_all, read_dir};
4use std::io::{BufReader, Cursor, Error, Read, Seek, SeekFrom, Write};
5use std::path::{Path, PathBuf};
6
7use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
8use linked_hash_map::LinkedHashMap;
9use regex::Regex;
10use sha1::{Digest, Sha1};
11use std::sync::LazyLock;
12
13#[expect(clippy::unwrap_used, reason = "the static patterns are valid regexes")]
14static BINARIZABLE_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"(?i)\.(rtm|p3d)$").unwrap());
15#[expect(clippy::unwrap_used, reason = "the static pattern is a valid regex")]
16static P3DO_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"(?i)\.p3do$").unwrap());
17
18use crate::binarize::{self, Binarizer};
19use crate::config::{Config, is_rapified};
20use crate::error::{ErrorExt, printable};
21use crate::fileid::FileId;
22use crate::io::WriteExt;
23use crate::p3d;
24use crate::preprocess::IncludeFolders;
25use crate::warning::{Warning, WarningSink};
26
27struct PBOHeader {
28    filename: String,
29    /// Raw name bytes, only set if the name is not valid UTF-8.
30    raw_filename: Option<Vec<u8>>,
31    packing_method: u32,
32    original_size: u32,
33    reserved: u32,
34    timestamp: u32,
35    data_size: u32,
36}
37
38/// What a PBO's header says about one entry.
39#[derive(Debug, Clone, PartialEq, Eq)]
40#[non_exhaustive]
41pub struct EntryHeader {
42    /// The entry name.
43    pub name: String,
44    /// The packing method (0 is stored, `0x43707273` is compressed).
45    pub packing_method: u32,
46    /// The size once decompressed.
47    pub original_size: u32,
48    /// The size as stored in the PBO.
49    pub data_size: u32,
50    /// The timestamp field of the entry header (Unix time, usually 0).
51    pub timestamp: u32,
52    /// The bytes the name is stored as in the PBO header (`name` is decoded from them).
53    pub name_bytes: Vec<u8>,
54}
55
56/// The header extensions as `(key, value)` pairs and the entry names, both in file order.
57pub type HeaderSummary = (Vec<(String, String)>, Vec<String>);
58
59/// Longest entry name or header extension string `PBO::read_headers` accepts.
60const MAX_HEADER_STRING: usize = 4096;
61/// Most entries `PBO::read_headers` accepts.
62const MAX_HEADER_ENTRIES: usize = 1 << 20;
63/// Most header extensions `PBO::read_headers` accepts.
64const MAX_HEADER_EXTENSIONS: usize = 1024;
65
66/// A NUL terminated string of at most `MAX_HEADER_STRING` bytes.
67fn read_bounded_cstring<I: Read>(input: &mut I) -> Result<Vec<u8>, Error> {
68    let mut bytes: Vec<u8> = Vec::new();
69    let mut buf = [0u8; 1];
70    loop {
71        input.read_exact(&mut buf)?;
72        if buf[0] == 0 {
73            return Ok(bytes);
74        }
75        if bytes.len() >= MAX_HEADER_STRING {
76            return Err(error!("PBO header string is too long."));
77        }
78        bytes.push(buf[0]);
79    }
80}
81
82/// Decodes an entry name. Names that are not valid UTF-8 are decoded as windows-1252, which maps all
83/// 256 byte values to distinct characters, so the original bytes are returned as well.
84fn decode_name(bytes: Vec<u8>) -> (String, Option<Vec<u8>>) {
85    match String::from_utf8(bytes) {
86        Ok(s) => (s, None),
87        Err(e) => {
88            let bytes = e.into_bytes();
89            let (decoded, _, _) = encoding_rs::WINDOWS_1252.decode(&bytes);
90            (decoded.into_owned(), Some(bytes))
91        }
92    }
93}
94
95/// Normalizes a PBO prefix: forward slashes become backslashes, leading and trailing separators are removed.
96fn normalize_prefix(prefix: &str, warn: bool, warnings: &mut dyn WarningSink) -> String {
97    let trimmed = prefix.trim();
98    let normalized = trimmed.replace('/', "\\");
99    let stripped = normalized.trim_matches('\\');
100    if warn && stripped.len() != normalized.len() {
101        warnings.warn(Warning::new(
102            Some("prefix-slash"),
103            format!("Removed leading/trailing slashes from prefix {trimmed:?}."),
104        ));
105    }
106    stripped.to_string()
107}
108
109/// Sets a header extension: a repeated key keeps its first position and takes the last value, so
110/// the order of the extensions is the order of the file.
111fn set_extension(extensions: &mut LinkedHashMap<String, String>, key: &str, value: String) {
112    if let Some(existing) = extensions.get_mut(key) {
113        *existing = value;
114    } else {
115        extensions.insert(key.to_string(), value);
116    }
117}
118
119/// Parses `$PBOPREFIX$` into header extensions: a bare line is the prefix, `key=value` lines are
120/// extensions. Prefix slashes are normalized (`warn` controls the `prefix-slash` warning).
121fn parse_prefix_file(
122    content: &str,
123    header_extensions: &mut LinkedHashMap<String, String>,
124    warn: bool,
125    warnings: &mut dyn WarningSink,
126) {
127    for l in content.lines() {
128        if l.is_empty() {
129            break;
130        }
131
132        match l.split_once('=') {
133            None => {
134                set_extension(
135                    header_extensions,
136                    "prefix",
137                    normalize_prefix(l, warn, warnings),
138                );
139            }
140            Some((key, value)) if key == "prefix" => {
141                set_extension(
142                    header_extensions,
143                    key,
144                    normalize_prefix(value, warn, warnings),
145                );
146            }
147            Some((key, value)) => {
148                set_extension(header_extensions, key, value.to_string());
149            }
150        }
151    }
152}
153
154/// PBO file
155///
156/// # Examples
157///
158/// ```
159/// # use std::path::Path;
160/// # use dayzmake_core::pbo::{PBO, PackOptions};
161/// # use dayzmake_core::warning::Warnings;
162/// let pbo = PBO::from_directory(Path::new("src"), &PackOptions::pack(), None, &mut Warnings::new()).expect("Failed to create PBO");
163///
164/// assert!(pbo.entry_names().any(|name| name == "lib.rs"));
165///
166/// let mut cursor = pbo.to_cursor().unwrap();
167/// let reread = PBO::read(&mut cursor).unwrap();
168///
169/// assert!(reread.checksum().is_some());
170/// ```
171pub struct PBO {
172    /// The PBO's files in header order, keyed by name.
173    files: LinkedHashMap<String, Cursor<Box<[u8]>>>,
174    /// Header extensions (`key=value`), including the prefix under the key `prefix`.
175    header_extensions: LinkedHashMap<String, String>,
176    /// Original bytes of entry names that are not valid UTF-8, keyed by their windows-1252 decoding
177    /// (the key used in `files`).
178    raw_names: HashMap<String, Vec<u8>>,
179    /// The stored bytes of every header extension in the order of `header_extensions`; empty for a
180    /// PBO that was not read.
181    raw_pairs: Vec<(Vec<u8>, Vec<u8>)>,
182    headers: Vec<PBOHeader>,
183    /// only defined when reading existing PBOs, for created PBOs this is calculated during writing
184    /// and included in the output
185    checksum: Option<Vec<u8>>,
186    /// The SHA-1 of the bytes that were read (header block and entry data, everything before the
187    /// trailer); only defined together with `checksum`.
188    computed_checksum: Option<Vec<u8>>,
189}
190
191/// Hashes everything that is read through it.
192struct HashingReader<'a, I> {
193    inner: &'a mut I,
194    hash: Sha1,
195}
196
197impl<I: Read> Read for HashingReader<'_, I> {
198    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
199        let n = self.inner.read(buf)?;
200        if let Some(read) = buf.get(..n) {
201            self.hash.update(read);
202        }
203        Ok(n)
204    }
205}
206
207impl PBOHeader {
208    fn read<I: Read>(input: &mut I) -> Result<PBOHeader, Error> {
209        let (filename, raw_filename) = decode_name(read_bounded_cstring(input)?);
210        Ok(PBOHeader {
211            filename,
212            raw_filename,
213            packing_method: input.read_u32::<LittleEndian>()?,
214            original_size: input.read_u32::<LittleEndian>()?,
215            reserved: input.read_u32::<LittleEndian>()?,
216            timestamp: input.read_u32::<LittleEndian>()?,
217            data_size: input.read_u32::<LittleEndian>()?,
218        })
219    }
220
221    fn write<O: Write>(&self, output: &mut O) -> Result<(), Error> {
222        match &self.raw_filename {
223            Some(raw) => output.write_cstring(raw)?,
224            None => output.write_cstring(&self.filename)?,
225        }
226        output.write_u32::<LittleEndian>(self.packing_method)?;
227        output.write_u32::<LittleEndian>(self.original_size)?;
228        output.write_u32::<LittleEndian>(self.reserved)?;
229        output.write_u32::<LittleEndian>(self.timestamp)?;
230        output.write_u32::<LittleEndian>(self.data_size)?;
231        Ok(())
232    }
233}
234
235/// The parsed header block of a PBO: the header extensions and the entry headers.
236struct HeaderBlock {
237    extensions: LinkedHashMap<String, String>,
238    /// The stored bytes of every extension `(key, value)`, in the order of `extensions`.
239    raw_pairs: Vec<(Vec<u8>, Vec<u8>)>,
240    headers: Vec<PBOHeader>,
241}
242
243/// Parses the header block of a PBO, up to and including the empty terminating header. The data of the
244/// first entry starts right after it.
245///
246/// The input is untrusted: every string is limited to `MAX_HEADER_STRING` bytes, the number of entries
247/// to `MAX_HEADER_ENTRIES` and of header extensions to `MAX_HEADER_EXTENSIONS`, and nothing is allocated
248/// from a size in the file.
249fn read_header_block<I: Read>(input: &mut I) -> Result<HeaderBlock, Error> {
250    let mut block = HeaderBlock {
251        extensions: LinkedHashMap::new(),
252        raw_pairs: Vec::new(),
253        headers: Vec::new(),
254    };
255    let mut first = true;
256    loop {
257        let header = PBOHeader::read(input)?;
258        // todo: garbage filter
259
260        if header.packing_method == 0x5665_7273 {
261            if !first {
262                return Err(error!("Duplicate version header in PBO."));
263            }
264            loop {
265                let key_bytes = read_bounded_cstring(input)?;
266                let (key, _) = decode_name(key_bytes.clone());
267                if key.is_empty() {
268                    break;
269                }
270                if block.extensions.len() >= MAX_HEADER_EXTENSIONS {
271                    return Err(error!("PBO has too many header extensions."));
272                }
273                let value_bytes = read_bounded_cstring(input)?;
274                let (value, _) = decode_name(value_bytes.clone());
275                match block.extensions.keys().position(|k| *k == key) {
276                    Some(at) => {
277                        if let Some(pair) = block.raw_pairs.get_mut(at) {
278                            pair.1 = value_bytes;
279                        }
280                    }
281                    None => block.raw_pairs.push((key_bytes, value_bytes)),
282                }
283                set_extension(&mut block.extensions, &key, value);
284            }
285        } else if header.filename.is_empty() {
286            break;
287        } else {
288            if block.headers.len() >= MAX_HEADER_ENTRIES {
289                return Err(error!("PBO has too many entries."));
290            }
291            block.headers.push(header);
292        }
293        first = false;
294    }
295    Ok(block)
296}
297
298/// An entry name with its decompressed data, or the reason it cannot be read.
299#[derive(Debug)]
300pub struct SelectedEntry {
301    name: String,
302    data: Result<Vec<u8>, Error>,
303    over_limit: bool,
304}
305
306impl SelectedEntry {
307    /// The entry name.
308    #[must_use]
309    pub fn name(&self) -> &str {
310        &self.name
311    }
312
313    /// The decompressed data of the entry.
314    ///
315    /// # Errors
316    ///
317    /// Returns the error that kept the entry from being decompressed.
318    pub fn data(&self) -> Result<&[u8], &Error> {
319        self.data.as_ref().map(Vec::as_slice)
320    }
321
322    /// The decompressed data of the entry, moved out without a copy.
323    ///
324    /// # Errors
325    ///
326    /// Returns the error that kept the entry from being decompressed.
327    pub fn into_data(self) -> Result<Vec<u8>, Error> {
328        self.data
329    }
330
331    /// Whether [`PBO::read_entries_tolerant`] left the entry unread because the byte limit was reached
332    /// (its [`data`](Self::data) is then an error).
333    #[must_use]
334    pub fn is_over_limit(&self) -> bool {
335        self.over_limit
336    }
337}
338
339/// The entries of a PBO that [`PBO::read_entries`] selected.
340#[derive(Debug)]
341pub struct PboSelection {
342    header_extensions: LinkedHashMap<String, String>,
343    names: Vec<String>,
344    entries: Vec<SelectedEntry>,
345}
346
347impl PboSelection {
348    /// All entry names in file order.
349    #[must_use]
350    pub fn names(&self) -> &[String] {
351        &self.names
352    }
353
354    /// The selected entries in file order with their decompressed data; an entry that cannot be
355    /// decompressed is an error of its own.
356    #[must_use]
357    pub fn entries(&self) -> &[SelectedEntry] {
358        &self.entries
359    }
360
361    /// The selected entries, moved out of the selection.
362    #[must_use]
363    pub fn into_entries(self) -> Vec<SelectedEntry> {
364        self.entries
365    }
366
367    /// The value of a header extension (the prefix is the key `prefix`).
368    #[must_use]
369    pub fn header_extension(&self, key: &str) -> Option<&str> {
370        self.header_extensions.get(key).map(String::as_str)
371    }
372
373    /// The header extensions (`key=value`) in file order.
374    pub fn header_extensions(&self) -> impl Iterator<Item = (&str, &str)> {
375        self.header_extensions
376            .iter()
377            .map(|(k, v)| (k.as_str(), v.as_str()))
378    }
379}
380
381/// Where one entry of a PBO is stored: what [`read_index`] returns, so a reader can seek to the data.
382pub(crate) struct IndexEntry {
383    pub(crate) name: String,
384    /// The stored name is not valid UTF-8 (`name` is its windows-1252 decoding).
385    pub(crate) non_utf8: bool,
386    pub(crate) offset: u64,
387    pub(crate) size: u64,
388    pub(crate) original_size: u32,
389    pub(crate) compressed: bool,
390}
391
392/// The header block of a PBO and the position of every entry's data.
393pub(crate) struct PboIndex {
394    pub(crate) prefix: Option<String>,
395    pub(crate) prefix_bytes: Option<Vec<u8>>,
396    pub(crate) entries: Vec<IndexEntry>,
397    /// The length of the file; the data of an entry may lie past it in a damaged PBO.
398    pub(crate) len: u64,
399}
400
401/// Reads the header block of a seekable PBO without reading any entry data.
402///
403/// The input is untrusted: the header block is bounded like [`PBO::read_headers`] and nothing is
404/// allocated from a size in the file; offsets use checked arithmetic.
405pub(crate) fn read_index<I: Read + Seek>(input: &mut I) -> Result<PboIndex, Error> {
406    let len = input.seek(SeekFrom::End(0))?;
407    input.seek(SeekFrom::Start(0))?;
408    let mut reader = BufReader::new(&mut *input);
409    let block = read_header_block(&mut reader)?;
410    let mut offset = reader.stream_position()?;
411    let mut entries = Vec::with_capacity(block.headers.len());
412    for h in &block.headers {
413        let size = u64::from(h.data_size);
414        entries.push(IndexEntry {
415            name: h.filename.clone(),
416            non_utf8: h.raw_filename.is_some(),
417            offset,
418            size,
419            original_size: h.original_size,
420            compressed: h.packing_method == PACKING_COMPRESSED,
421        });
422        offset = offset
423            .checked_add(size)
424            .ok_or_else(|| error!("PBO entry sizes overflow."))?;
425    }
426    let prefix_bytes = (block.raw_pairs.len() == block.extensions.len())
427        .then(|| {
428            let at = block.extensions.keys().position(|k| k == "prefix")?;
429            block.raw_pairs.get(at).map(|(_, value)| value.clone())
430        })
431        .flatten();
432    Ok(PboIndex {
433        prefix: block.extensions.get("prefix").cloned(),
434        prefix_bytes,
435        entries,
436        len,
437    })
438}
439
440/// Decompresses the stored bytes of a "Cprs" entry (see `lzss_decompress`).
441pub(crate) fn decompress_entry(data: &[u8], original_size: u32) -> Result<Vec<u8>, Error> {
442    lzss_decompress(data, original_size as usize)
443}
444
445/// Packing method of entries compressed with Bohemia's LZSS variant ("Cprs").
446const PACKING_COMPRESSED: u32 = 0x4370_7273;
447
448/// Decompresses a "Cprs" PBO entry (Bohemia's LZSS); the 4 byte checksum after the data is
449/// ignored.
450fn lzss_decompress(data: &[u8], original_size: usize) -> Result<Vec<u8>, Error> {
451    crate::lzss::decompress(data, original_size, "PBO entry").map(|(out, _)| out)
452}
453
454/// Matches `s` against `pattern`, where `*` stands for any run of characters, including none.
455fn matches_glob(s: &str, pattern: &str) -> bool {
456    let s: Vec<char> = s.chars().collect();
457    let pattern: Vec<char> = pattern.chars().collect();
458    let (mut si, mut pi) = (0, 0);
459    // pattern position after the last `*` and the string position it currently covers up to
460    let mut backtrack: Option<(usize, usize)> = None;
461
462    while si < s.len() {
463        match pattern.get(pi) {
464            Some('*') => {
465                pi += 1;
466                backtrack = Some((pi, si));
467            }
468            Some(c) if Some(c) == s.get(si) => {
469                pi += 1;
470                si += 1;
471            }
472            _ => match backtrack {
473                Some((after_star, covered)) => {
474                    pi = after_star;
475                    si = covered + 1;
476                    backtrack = Some((after_star, si));
477                }
478                None => return false,
479            },
480        }
481    }
482
483    pattern
484        .get(pi..)
485        .is_some_and(|rest| rest.iter().all(|&c| c == '*'))
486}
487
488fn file_allowed(name: &str, exclude_patterns: &[String]) -> bool {
489    for pattern in exclude_patterns {
490        if matches_glob(name, pattern) {
491            return false;
492        }
493    }
494
495    true
496}
497
498/// The bounds of [`PBO::read_entries_tolerant`].
499#[derive(Debug, Clone, Copy, PartialEq, Eq)]
500#[non_exhaustive]
501pub struct TolerantRead {
502    /// The most bytes of decompressed entry data the selection reads in total.
503    pub max_bytes: u64,
504}
505
506impl TolerantRead {
507    /// Bounds the selection to `max_bytes` of decompressed entry data.
508    #[must_use]
509    pub fn new(max_bytes: u64) -> Self {
510        TolerantRead { max_bytes }
511    }
512}
513
514/// What [`PBO::from_directory`] does with a folder.
515#[derive(Debug, Clone, Default)]
516#[non_exhaustive]
517pub struct PackOptions {
518    /// Binarize models and rapify configs (`build`) instead of packing the files as they are.
519    pub build: bool,
520    /// Glob patterns of files left out of the PBO.
521    pub exclude: Vec<String>,
522    /// Folders searched for absolute includes in configs and model dependencies.
523    pub include_folders: Vec<PathBuf>,
524    /// Folders checked for absolute includes only directly (`<folder>/<include path>`), never walked. The CLI puts
525    /// the current working directory here (#66).
526    pub direct_include_folders: Vec<PathBuf>,
527    /// Header extensions (`key`, `value`) set after `$PBOPREFIX$` was read; they win on a clash.
528    pub header_extensions: Vec<(String, String)>,
529    /// Paths the folder walk skips (the output file of a build inside the source folder), compared after
530    /// canonicalizing. Hidden temp files of such a target (see [`atomic_temp_prefix`]) next to it are skipped too.
531    pub exclude_paths: Vec<PathBuf>,
532    /// Also skip the file this process's standard output is redirected to, when it is a regular file (`dayzmake
533    /// pack m > m/out.pbo` creates the file inside the folder before the walk). A terminal, a pipe, `/dev/null`
534    /// or a closed stdout excludes nothing.
535    pub exclude_stdout: bool,
536}
537
538/// The file-name prefix of the temp files written next to the target `name` before they are renamed into place
539/// (`.<name>.dayzmake-tmp-<pid>-<n>`); a build leaves them out of the PBO.
540#[must_use]
541pub fn atomic_temp_prefix(name: &str) -> String {
542    format!(".{name}.dayzmake-tmp-")
543}
544
545/// A file the folder walk skips.
546struct Excluded {
547    /// The canonical folder, name and temp prefix of an excluded path; none for standard output, which has no path.
548    by_name: Option<ExcludedName>,
549    /// The identity of the excluded file when it exists, for the comparison that is independent of spelling.
550    id: Option<FileId>,
551}
552
553/// An excluded path split into its canonical folder and file name.
554struct ExcludedName {
555    folder: PathBuf,
556    name: std::ffi::OsString,
557    /// Lower-cased temp prefix: the temp file does not exist yet, so it is matched by name.
558    temp_prefix: String,
559}
560
561fn excluded_paths(options: &PackOptions) -> Vec<Excluded> {
562    let mut list: Vec<Excluded> = options
563        .exclude_paths
564        .iter()
565        .filter_map(|p| {
566            let name = p.file_name()?.to_owned();
567            let parent = p.parent().filter(|d| !d.as_os_str().is_empty());
568            // fails open: an exclude whose folder cannot be resolved matches nothing (the folder exists in practice,
569            // the temp file was created there)
570            let folder = std::fs::canonicalize(parent.unwrap_or(Path::new("."))).ok()?;
571            let temp_prefix = atomic_temp_prefix(&name.to_string_lossy()).to_lowercase();
572            let id = FileId::of(&folder.join(&name));
573            Some(Excluded {
574                by_name: Some(ExcludedName {
575                    folder,
576                    name,
577                    temp_prefix,
578                }),
579                id,
580            })
581        })
582        .collect();
583    if options.exclude_stdout
584        && let Some(id) = FileId::stdout()
585    {
586        list.push(Excluded {
587            by_name: None,
588            id: Some(id),
589        });
590    }
591    list
592}
593
594/// Whether `path` is the build's own output or a temp file of it.
595///
596/// The output is recognised by file identity when it exists (case-insensitive file systems, hard links and symlinks
597/// name it differently), by exact name in the same folder otherwise. The temp prefix is matched by name, ignoring
598/// case on every platform: the temp file does not exist yet, and a stale hidden `.X.dayzmake-tmp-` file that differs
599/// only in case is never wanted in a PBO.
600fn is_excluded(path: &Path, excluded: &[Excluded]) -> bool {
601    let Some(name) = path.file_name() else {
602        return false;
603    };
604    let name_lower = name.to_string_lossy().to_lowercase();
605    // canonicalize and open only when needed, once per path
606    let mut folder: Option<Option<PathBuf>> = None;
607    let mut id: Option<Option<FileId>> = None;
608    excluded.iter().any(|e| {
609        if let Some(n) = &e.by_name
610            && (name == n.name || name_lower.starts_with(&n.temp_prefix))
611        {
612            let folder = folder.get_or_insert_with(|| {
613                path.parent()
614                    .filter(|d| !d.as_os_str().is_empty())
615                    .map_or_else(
616                        // fails open like `excluded_paths`: an unresolvable folder is never equal to an excluded one
617                        || std::fs::canonicalize(".").ok(),
618                        |d| std::fs::canonicalize(d).ok(),
619                    )
620            });
621            if folder.as_deref() == Some(n.folder.as_path()) {
622                return true;
623            }
624        }
625        // an unopenable file (gone meanwhile, no permission) is not the same file; opened lazily: only when
626        // there is an identity to compare with
627        e.id.as_ref()
628            .is_some_and(|own| id.get_or_insert_with(|| FileId::of(path)).as_ref() == Some(own))
629    })
630}
631
632impl PackOptions {
633    /// Options for packing a folder as it is.
634    #[must_use]
635    pub fn pack() -> PackOptions {
636        PackOptions::default()
637    }
638
639    /// Options for building a folder: binarize and rapify where needed.
640    #[must_use]
641    pub fn build() -> PackOptions {
642        PackOptions {
643            build: true,
644            ..PackOptions::default()
645        }
646    }
647}
648
649impl Default for PBO {
650    fn default() -> PBO {
651        PBO::new()
652    }
653}
654
655/// Rewrites `Warning.file` to the path relative to the addon folder when it lies inside it.
656struct AddonRelative<'a> {
657    /// The addon folder as given and canonicalised (includes are reported canonicalised).
658    roots: &'a [PathBuf; 2],
659    inner: &'a mut dyn WarningSink,
660}
661
662/// The addon folder as given and canonicalised, computed once per pack.
663fn addon_roots(directory: &Path) -> [PathBuf; 2] {
664    // canonicalize fails for a missing or unreadable folder; matching against the path as given still
665    // works, so warnings are not lost
666    let canonical = directory
667        .canonicalize()
668        .unwrap_or_else(|_| directory.to_path_buf());
669    [directory.to_path_buf(), canonical]
670}
671
672impl WarningSink for AddonRelative<'_> {
673    fn warn(&mut self, mut warning: Warning) {
674        if let Some(file) = &warning.file {
675            let file = Path::new(file);
676            if let Some(relative) = self
677                .roots
678                .iter()
679                .find_map(|root| file.strip_prefix(root).ok())
680            {
681                warning.file = Some(relative.to_string_lossy().into_owned());
682            }
683        }
684        self.inner.warn(warning);
685    }
686
687    fn is_suppressed(&self, name: Option<&str>) -> bool {
688        self.inner.is_suppressed(name)
689    }
690}
691
692impl PBO {
693    /// An empty PBO without entries and header extensions.
694    #[must_use]
695    pub fn new() -> PBO {
696        PBO {
697            files: LinkedHashMap::new(),
698            header_extensions: LinkedHashMap::new(),
699            raw_names: HashMap::new(),
700            raw_pairs: Vec::new(),
701            headers: Vec::new(),
702            checksum: None,
703            computed_checksum: None,
704        }
705    }
706
707    /// The entries in the order the PBO has them: header order for a PBO that was read and not
708    /// modified, the order [`PBO::write`] uses (sorted by name) for any other. Data is as stored, so
709    /// compressed entries stay compressed; see [`PBO::file_data`].
710    pub fn entries(&self) -> impl Iterator<Item = (&str, &[u8])> {
711        self.ordered_files()
712            .into_iter()
713            .map(|(name, cursor)| (name, cursor.get_ref().as_ref()))
714    }
715
716    /// The entry names, in the order of [`PBO::entries`].
717    pub fn entry_names(&self) -> impl Iterator<Item = &str> {
718        self.entries().map(|(name, _)| name)
719    }
720
721    /// Adds an entry, or replaces the data of the entry with the same name.
722    /// Replacing an existing entry also replaces its stored name bytes with the new name's.
723    ///
724    /// # Errors
725    ///
726    /// `/` in the name is stored as `\`. Returns an error if the name has an empty component
727    /// (leading, trailing or doubled separator, or no name at all) or is one
728    /// [`safe_relative_path`] rejects (drive letter, `..` component and so on). Modifying a PBO
729    /// that was read drops its stored checksum: it is signed as the PBO that would be written.
730    pub fn insert_entry(&mut self, name: impl Into<String>, data: Vec<u8>) -> Result<(), Error> {
731        let name = name.into().replace('/', "\\");
732        if safe_relative_path(&name).is_none() {
733            return Err(error!("Unsafe PBO entry name \"{}\".", printable(&name)));
734        }
735        self.modified(&name);
736        // the new name is stored as the UTF-8 it was given in, not as the bytes of the entry it replaces
737        self.raw_names.remove(&name);
738        self.files
739            .insert(name, Cursor::new(data.into_boxed_slice()));
740        Ok(())
741    }
742
743    /// Removes an entry and returns its stored data.
744    pub fn remove_entry(&mut self, name: &str) -> Option<Vec<u8>> {
745        let removed = self.files.remove(name)?;
746        self.raw_names.remove(name);
747        self.modified(name);
748        Some(removed.into_inner().into_vec())
749    }
750
751    /// The header extensions (`key=value`) in file order, including the prefix.
752    pub fn header_extensions(&self) -> impl Iterator<Item = (&str, &str)> {
753        self.header_extensions
754            .iter()
755            .map(|(k, v)| (k.as_str(), v.as_str()))
756    }
757
758    /// The value of a header extension.
759    #[must_use]
760    pub fn header_extension(&self, key: &str) -> Option<&str> {
761        self.header_extensions.get(key).map(String::as_str)
762    }
763
764    /// Sets a header extension; a repeated key keeps its position and takes the new value.
765    pub fn set_header_extension(&mut self, key: impl Into<String>, value: impl Into<String>) {
766        let (key, value) = (key.into(), value.into());
767        // the stored bytes stay in step with the extensions; the new value is stored as UTF-8
768        if self.raw_pairs.len() == self.header_extensions.len() {
769            match self.header_extensions.keys().position(|k| *k == key) {
770                Some(at) => {
771                    if let Some(pair) = self.raw_pairs.get_mut(at) {
772                        pair.1 = value.as_bytes().to_vec();
773                    }
774                }
775                None => self
776                    .raw_pairs
777                    .push((key.as_bytes().to_vec(), value.as_bytes().to_vec())),
778            }
779        } else {
780            self.raw_pairs.clear();
781        }
782        self.checksum = None;
783        self.computed_checksum = None;
784        set_extension(&mut self.header_extensions, &key, value);
785    }
786
787    /// The PBO prefix (the header extension `prefix`).
788    #[must_use]
789    pub fn prefix(&self) -> Option<&str> {
790        self.header_extension("prefix")
791    }
792
793    /// The SHA-1 trailer of a PBO that was read and not modified; `None` otherwise.
794    #[must_use]
795    pub fn checksum(&self) -> Option<&[u8]> {
796        self.checksum.as_deref()
797    }
798
799    /// The SHA-1 of the bytes of a PBO that was read and not modified (header block and entry
800    /// data, everything before the trailer); `None` otherwise. A PBO whose stored
801    /// [`checksum`](PBO::checksum) differs from it is corrupt or was tampered with.
802    #[must_use]
803    pub fn computed_checksum(&self) -> Option<&[u8]> {
804        self.computed_checksum.as_deref()
805    }
806
807    /// A stored entry changes: the stored trailer no longer describes the PBO, and the header of
808    /// the entry (packing method) no longer describes its data.
809    fn modified(&mut self, name: &str) {
810        self.checksum = None;
811        self.computed_checksum = None;
812        self.headers.retain(|h| h.filename != name);
813    }
814
815    /// The entries in header order (read, unmodified PBO) or write order (any other).
816    fn ordered_files(&self) -> Vec<(&str, &Cursor<Box<[u8]>>)> {
817        let mut files: Vec<(&str, &Cursor<Box<[u8]>>)> =
818            self.files.iter().map(|(a, b)| (a.as_str(), b)).collect();
819        if self.checksum.is_none() {
820            files.sort_by_cached_key(|f| self.name_bytes(f.0).to_ascii_lowercase());
821        }
822        files
823    }
824
825    /// The SHA-1 of the PBO: the one computed while reading for a PBO that was read (an error if
826    /// the stored trailer differs; `signing` adds the advice to repack), the one [`PBO::write`] would produce otherwise (nothing is
827    /// kept in memory or on disk for it).
828    #[cfg(feature = "sign")]
829    pub(crate) fn trailer_checksum(&self, signing: bool) -> Result<Vec<u8>, Error> {
830        match (&self.checksum, &self.computed_checksum) {
831            (Some(stored), Some(computed)) => {
832                if stored == computed {
833                    Ok(computed.clone())
834                } else {
835                    Err(error!(
836                        "PBO checksum mismatch: the stored SHA-1 trailer does not match the SHA-1 of the PBO's contents (the PBO is corrupt or was modified){}.",
837                        if signing {
838                            "; repack it before signing"
839                        } else {
840                            ""
841                        }
842                    ))
843                }
844            }
845            _ => self.write_with_checksum(&mut std::io::sink()),
846        }
847    }
848
849    /// The entry headers of a PBO that was read, in header order (empty for one made by
850    /// [`PBO::from_directory`]).
851    #[must_use]
852    pub fn entry_headers(&self) -> Vec<EntryHeader> {
853        self.headers
854            .iter()
855            .map(|h| EntryHeader {
856                name: h.filename.clone(),
857                packing_method: h.packing_method,
858                original_size: h.original_size,
859                data_size: h.data_size,
860                timestamp: h.timestamp,
861                name_bytes: h
862                    .raw_filename
863                    .clone()
864                    .unwrap_or_else(|| h.filename.as_bytes().to_vec()),
865            })
866            .collect()
867    }
868
869    /// Returns the bytes an entry name is stored as in the PBO header.
870    #[must_use]
871    pub fn name_bytes(&self, name: &str) -> Vec<u8> {
872        self.raw_names
873            .get(name)
874            .cloned()
875            .unwrap_or_else(|| name.as_bytes().to_vec())
876    }
877
878    /// The header extensions as `(key, value)` bytes, in the order of [`PBO::header_extensions`]:
879    /// what the PBO header stores for a PBO that was read (a value set since is its UTF-8 bytes),
880    /// the UTF-8 bytes of the strings otherwise. A repeated key has the bytes of its
881    /// first key and its last value.
882    #[must_use]
883    pub fn header_extensions_bytes(&self) -> Vec<(Vec<u8>, Vec<u8>)> {
884        if self.raw_pairs.len() == self.header_extensions.len() {
885            return self.raw_pairs.clone();
886        }
887        self.header_extensions()
888            .map(|(k, v)| (k.as_bytes().to_vec(), v.as_bytes().to_vec()))
889            .collect()
890    }
891
892    /// The bytes the prefix is stored as: the value of the extension `prefix`.
893    pub(crate) fn prefix_bytes(&self) -> Option<Vec<u8>> {
894        let at = self.header_extensions.keys().position(|k| k == "prefix")?;
895        self.header_extensions_bytes()
896            .into_iter()
897            .nth(at)
898            .map(|(_, value)| value)
899    }
900
901    /// Reads an existing PBO from input.
902    ///
903    /// # Errors
904    ///
905    /// Returns an error if the input is not a valid PBO.
906    pub fn read<I: Read>(input: &mut I) -> Result<PBO, Error> {
907        let mut hashing = HashingReader {
908            inner: input,
909            hash: Sha1::new(),
910        };
911        let input = &mut hashing;
912        let HeaderBlock {
913            extensions: header_extensions,
914            raw_pairs,
915            headers,
916        } = read_header_block(input)?;
917
918        let mut files: LinkedHashMap<String, Cursor<Box<[u8]>>> = LinkedHashMap::new();
919        let mut raw_names: HashMap<String, Vec<u8>> = HashMap::new();
920        for header in &headers {
921            // two names that decode alike are one entry whose data is the last one's: keep that name's bytes
922            match &header.raw_filename {
923                Some(raw) => {
924                    raw_names.insert(header.filename.clone(), raw.clone());
925                }
926                None => {
927                    raw_names.remove(&header.filename);
928                }
929            }
930            // never preallocate the full length from untrusted input
931            let mut buffer: Vec<u8> = Vec::new();
932            let got = input
933                .take(u64::from(header.data_size))
934                .read_to_end(&mut buffer)?;
935            if got != header.data_size as usize {
936                return Err(error!(
937                    "PBO entry \"{}\" is truncated ({} of {} bytes).",
938                    printable(&header.filename),
939                    got,
940                    header.data_size
941                ));
942            }
943            files.insert(
944                header.filename.clone(),
945                Cursor::new(buffer.into_boxed_slice()),
946            );
947        }
948
949        // the trailer's SHA-1 covers everything before the 0 byte that precedes it
950        let computed_checksum = hashing.hash.clone().finalize().to_vec();
951        let input = hashing.inner;
952        let mut skip = [0u8; 1];
953        let _ = input.read(&mut skip)?;
954        let mut checksum = vec![0; 20];
955        input.read_exact(&mut checksum)?;
956
957        Ok(PBO {
958            files,
959            header_extensions,
960            raw_names,
961            raw_pairs,
962            headers,
963            checksum: Some(checksum),
964            computed_checksum: Some(computed_checksum),
965        })
966    }
967
968    /// Reads only the header block of a PBO: the header extensions and the entry names, in file order.
969    /// The entry data is never read, so this is cheap for PBOs of any size. Pass a buffered reader.
970    ///
971    /// The input is untrusted: every name is limited to `MAX_HEADER_STRING` bytes, the number of entries
972    /// and extensions are limited, and nothing is allocated from a size in the file.
973    ///
974    /// # Errors
975    ///
976    /// Returns an error if the header block is truncated, malformed or exceeds the limits.
977    /// The extensions are `(key, value)` pairs in file order.
978    pub fn read_headers<I: Read>(input: &mut I) -> Result<HeaderSummary, Error> {
979        let block = read_header_block(input)?;
980        let names = block.headers.into_iter().map(|h| h.filename).collect();
981        Ok((block.extensions.into_iter().collect(), names))
982    }
983
984    /// Reads the header block of a seekable PBO and only the entries `wanted` accepts, by seeking to their
985    /// data. Memory use is bounded by the selected entries, not by the size of the PBO, which can be many
986    /// hundred MB.
987    ///
988    /// The input is untrusted: the header block is bounded like `read_headers`, and an entry whose data
989    /// selected for reading does not lie inside the file is an error (nothing is allocated from a size before it is checked
990    /// against the file length).
991    ///
992    /// # Errors
993    ///
994    /// Returns an error if the header block is malformed or exceeds the limits, or the data of a selected
995    /// entry is truncated.
996    pub fn read_entries<I: Read + Seek>(
997        input: &mut I,
998        wanted: impl Fn(&str) -> bool,
999    ) -> Result<PboSelection, Error> {
1000        Self::read_selected(input, wanted, None)
1001    }
1002
1003    /// Like [`PBO::read_entries`], but a damaged entry does not fail the whole selection, and the
1004    /// selection is bounded.
1005    ///
1006    /// A selected entry whose data is truncated or cannot be decompressed is an error of its own
1007    /// ([`SelectedEntry::data`]). The decompressed sizes of the selected entries are added up in file
1008    /// order; the first entry that would take the total past [`TolerantRead::max_bytes`] is not read, and neither is any
1009    /// selected entry after it (a smaller later one included); each reports [`SelectedEntry::is_over_limit`]. A malformed header
1010    /// block is still an error.
1011    ///
1012    /// # Errors
1013    ///
1014    /// Returns an error if the header block is malformed or exceeds the limits, or the entry sizes
1015    /// overflow.
1016    pub fn read_entries_tolerant<I: Read + Seek>(
1017        input: &mut I,
1018        wanted: impl Fn(&str) -> bool,
1019        options: &TolerantRead,
1020    ) -> Result<PboSelection, Error> {
1021        Self::read_selected(input, wanted, Some(options.max_bytes))
1022    }
1023
1024    /// `limit` set means the tolerant mode.
1025    fn read_selected<I: Read + Seek>(
1026        input: &mut I,
1027        wanted: impl Fn(&str) -> bool,
1028        limit: Option<u64>,
1029    ) -> Result<PboSelection, Error> {
1030        let len = input.seek(SeekFrom::End(0))?;
1031        input.seek(SeekFrom::Start(0))?;
1032        let mut reader = BufReader::new(&mut *input);
1033        let block = read_header_block(&mut reader)?;
1034        let mut offset = reader.stream_position()?;
1035        let mut entries = Vec::new();
1036        let mut total: u64 = 0;
1037        let mut exhausted = false;
1038        for h in &block.headers {
1039            let size = u64::from(h.data_size);
1040            let end = offset
1041                .checked_add(size)
1042                .ok_or_else(|| error!("PBO entry sizes overflow."))?;
1043            if wanted(&h.filename) {
1044                let compressed = h.packing_method == PACKING_COMPRESSED;
1045                let unpacked = if compressed {
1046                    u64::from(h.original_size)
1047                } else {
1048                    size
1049                };
1050                let failed = |why: Error, over_limit: bool| SelectedEntry {
1051                    name: h.filename.clone(),
1052                    data: Err(why),
1053                    over_limit,
1054                };
1055                if end > len {
1056                    let why = error!(
1057                        "PBO entry \"{}\" is truncated (its data ends past the end of the file).",
1058                        printable(&h.filename)
1059                    );
1060                    if limit.is_none() {
1061                        return Err(why);
1062                    }
1063                    entries.push(failed(why, false));
1064                    offset = end;
1065                    continue;
1066                }
1067                if let Some(max) = limit {
1068                    if exhausted {
1069                        entries.push(failed(
1070                            error!(
1071                                "PBO entry \"{}\" is left unread (the byte limit is reached).",
1072                                printable(&h.filename)
1073                            ),
1074                            true,
1075                        ));
1076                        offset = end;
1077                        continue;
1078                    }
1079                    let new_total = total.saturating_add(unpacked);
1080                    if new_total > max {
1081                        exhausted = true;
1082                        entries.push(failed(
1083                            error!(
1084                                "PBO entry \"{}\" is left unread (the byte limit is reached).",
1085                                printable(&h.filename)
1086                            ),
1087                            true,
1088                        ));
1089                        offset = end;
1090                        continue;
1091                    }
1092                    total = new_total;
1093                }
1094                reader.seek(SeekFrom::Start(offset))?;
1095                let mut data: Vec<u8> = Vec::new();
1096                (&mut reader).take(size).read_to_end(&mut data)?;
1097                let data = if compressed {
1098                    lzss_decompress(&data, h.original_size as usize).prepend_error(format!(
1099                        "Failed to decompress \"{}\":",
1100                        printable(&h.filename)
1101                    ))
1102                } else {
1103                    Ok(data)
1104                };
1105                entries.push(SelectedEntry {
1106                    name: h.filename.clone(),
1107                    data,
1108                    over_limit: false,
1109                });
1110            }
1111            offset = end;
1112        }
1113        Ok(PboSelection {
1114            header_extensions: block.extensions,
1115            names: block.headers.into_iter().map(|h| h.filename).collect(),
1116            entries,
1117        })
1118    }
1119
1120    /// Constructs a PBO from a directory, binarizing and rapifying where `options.build` is set.
1121    ///
1122    /// `options.exclude` contains glob patterns to exclude from the PBO, `options.include_folders`
1123    /// the paths to search recursively for absolute includes and `options.direct_include_folders` the paths
1124    /// checked only directly (generally the current working directory). `options.header_extensions` are applied after `$PBOPREFIX$`; for the same key
1125    /// the option wins. A `$NOBIN$` file in the directory turns `build` off. Models are only
1126    /// binarized when a `binarizer` is given; without one they are copied as-is with a warning.
1127    ///
1128    /// # Errors
1129    ///
1130    /// Returns an error if the directory cannot be read or a file cannot be processed.
1131    #[expect(
1132        clippy::too_many_lines,
1133        reason = "one branch per file kind keeps the packing loop readable"
1134    )]
1135    pub fn from_directory(
1136        directory: &Path,
1137        options: &PackOptions,
1138        mut binarizer: Option<&mut Binarizer>,
1139        warnings: &mut dyn WarningSink,
1140    ) -> Result<PBO, Error> {
1141        let mut binarize = options.build;
1142        let exclude_patterns = &options.exclude;
1143        let includefolders = IncludeFolders::new(options.include_folders.clone())
1144            .with_direct(options.direct_include_folders.clone());
1145        let search_roots: Vec<PathBuf> = options
1146            .include_folders
1147            .iter()
1148            .chain(&options.direct_include_folders)
1149            .cloned()
1150            .collect();
1151        let file_list = list_files(directory, &excluded_paths(options))?;
1152        let mut files: LinkedHashMap<String, Cursor<Box<[u8]>>> = LinkedHashMap::new();
1153        let mut header_extensions: LinkedHashMap<String, String> = LinkedHashMap::new();
1154
1155        if directory.join("$NOBIN$").exists() || directory.join("$NOBIN-NOTEST$").exists() {
1156            binarize = false;
1157        }
1158
1159        // the prefix is needed while binarizing, so read it before looking at the other files
1160        let mut pre_extensions: LinkedHashMap<String, String> = LinkedHashMap::new();
1161        for prefix_file in &["$PBOPREFIX$", "$PREFIX$"] {
1162            let prefix_path = directory.join(prefix_file);
1163            // a FIFO or device named like the prefix file would block the read; the walk below
1164            // reports it
1165            if !std::fs::metadata(&prefix_path).is_ok_and(|m| m.file_type().is_file()) {
1166                continue;
1167            }
1168            if let Ok(content) = std::fs::read_to_string(prefix_path) {
1169                parse_prefix_file(&content, &mut pre_extensions, false, warnings);
1170            }
1171        }
1172        let prefix: String = pre_extensions
1173            .get("prefix")
1174            .cloned()
1175            .unwrap_or_else(|| default_prefix(directory).unwrap_or_default());
1176
1177        let addon_files: HashSet<String> = file_list
1178            .iter()
1179            .filter_map(|p| p.strip_prefix(directory).ok())
1180            .filter_map(|p| p.to_str())
1181            .map(|p| p.replace('/', "\\").to_lowercase())
1182            .collect();
1183
1184        let addon_roots = addon_roots(directory);
1185        let mut seen_names: HashMap<String, String> = HashMap::new();
1186
1187        // Entries generated from source (the rapified config.cpp, a .p3do packed as .p3d) win over a
1188        // plain file of the same name, so find them first: the plain file is then skipped before it
1189        // is binarized or read. The gates are the ones of the loop below.
1190        // key -> (source file, stored entry name)
1191        let mut generated_names: HashMap<String, (String, String)> = HashMap::new();
1192        for path in &file_list {
1193            let Ok(relative) = path.strip_prefix(directory) else {
1194                continue;
1195            };
1196            let (pre_name, name, generated) = entry_name(relative, binarize);
1197            if !generated
1198                || !file_allowed(&pre_name, exclude_patterns)
1199                || std::fs::metadata(path).is_ok_and(|m| !m.file_type().is_file())
1200                || relative.to_str().is_none()
1201                || safe_relative_path(&name).is_none()
1202            {
1203                continue;
1204            }
1205            generated_names
1206                .entry(name.to_lowercase())
1207                .or_insert_with(|| (printable(&relative.to_string_lossy()), printable(&name)));
1208        }
1209
1210        for path in file_list {
1211            let Ok(mut relative) = path.strip_prefix(directory).map(Path::to_path_buf) else {
1212                continue;
1213            };
1214            let shown = printable(&relative.to_string_lossy());
1215            let (pre_name, name, generated) = entry_name(&relative, binarize);
1216            if binarize && relative.file_name() == Some(OsStr::new("config.cpp")) {
1217                relative = relative.with_file_name("config.bin");
1218            }
1219            // excluded files are silent, whatever they are
1220            if !file_allowed(&pre_name, exclude_patterns) {
1221                continue;
1222            }
1223            // only regular files (or links to them): a FIFO would block the build, a device never
1224            // ends. A path that cannot be inspected falls through to the open error below.
1225            if std::fs::metadata(&path).is_ok_and(|m| !m.file_type().is_file()) {
1226                warnings.warn(
1227                    Warning::new(
1228                        Some("unsupported-file"),
1229                        "Skipping a file that is not a regular file (FIFO, device or socket).",
1230                    )
1231                    .in_file(relative.to_string_lossy()),
1232                );
1233                continue;
1234            }
1235            if relative.to_str().is_none() || safe_relative_path(&pre_name).is_none() {
1236                warnings.warn(Warning::new(
1237                    Some("unsafe-path"),
1238                    format!("Skipping \"{shown}\": unsafe entry name."),
1239                ));
1240                continue;
1241            }
1242            // a .p3do is packed as .p3d (it is not binarized itself, so decide that first)
1243            let is_binarizable = BINARIZABLE_RE.is_match(&pre_name);
1244            // entry names compare case-insensitively; the first file in walk order wins, except
1245            // that an entry generated from source replaces a plain file of the same name (found
1246            // by the pre-pass above, so the plain file is skipped before it is processed)
1247            let key = name.to_lowercase();
1248            if !generated && let Some((source, stored)) = generated_names.get(&key) {
1249                warnings.warn(Warning::new(
1250                    Some("duplicate-entry"),
1251                    format!(
1252                        "Skipping \"{shown}\": the entry \"{stored}\" is generated from \"{source}\"."
1253                    ),
1254                ));
1255                continue;
1256            }
1257            if let Some(first) = seen_names.get(&key) {
1258                warnings.warn(Warning::new(
1259                    Some("duplicate-entry"),
1260                    format!(
1261                        "Skipping \"{shown}\": an entry named \"{}\" was already packed.",
1262                        printable(first)
1263                    ),
1264                ));
1265                continue;
1266            }
1267            seen_names.insert(key, name.clone());
1268
1269            let mut file =
1270                File::open(&path).prepend_error(format!("Failed to open \"{shown}\":"))?;
1271
1272            let prebinarized_as = if binarize && is_binarizable {
1273                binarize::binarized_description(&path)?
1274            } else {
1275                None
1276            };
1277            let prebinarized = prebinarized_as.is_some();
1278            if let Some(description) = prebinarized_as {
1279                warnings.warn(
1280                    Warning::new(
1281                        Some("prebinarized-file"),
1282                        format!("File is already binarized ({description}); copying it as-is."),
1283                    )
1284                    .in_file(relative.to_string_lossy()),
1285                );
1286            } else if binarize
1287                && is_binarizable
1288                && path
1289                    .extension()
1290                    .is_some_and(|e| e.eq_ignore_ascii_case("p3d"))
1291            {
1292                p3d::check_dependencies(
1293                    &path,
1294                    &relative.to_string_lossy(),
1295                    &prefix,
1296                    &addon_files,
1297                    &search_roots,
1298                    warnings,
1299                );
1300            }
1301
1302            if name == "$PBOPREFIX$" || name == "$PREFIX$" {
1303                let mut content = String::new();
1304                file.read_to_string(&mut content)
1305                    .prepend_error(format!("Failed to read \"{shown}\":"))?;
1306                parse_prefix_file(&content, &mut header_extensions, true, warnings);
1307            } else if binarize
1308                && ["cpp", "rvmat"]
1309                    .contains(&path.extension().and_then(|e| e.to_str()).unwrap_or(""))
1310            {
1311                let mut buffer: Vec<u8> = Vec::new();
1312                file.read_to_end(&mut buffer)
1313                    .prepend_error(format!("Failed to read \"{shown}\":"))?;
1314
1315                if is_rapified(&buffer) {
1316                    warnings.warn(
1317                        Warning::new(
1318                            Some("prerapified-file"),
1319                            "File is already rapified; copying it as-is.",
1320                        )
1321                        .in_file(relative.to_string_lossy()),
1322                    );
1323                    files.insert(name, Cursor::new(buffer.into_boxed_slice()));
1324                } else {
1325                    let mut addon_warnings = AddonRelative {
1326                        roots: &addon_roots,
1327                        inner: warnings,
1328                    };
1329                    let config = Config::read_in(
1330                        &mut Cursor::new(buffer),
1331                        Some(path.clone()),
1332                        &includefolders,
1333                        &mut addon_warnings,
1334                    )
1335                    .prepend_error("Failed to parse config:")?;
1336                    files.insert(name, config.to_cursor()?);
1337                }
1338            } else if let (Some(b), true) = (
1339                binarizer.as_deref_mut(),
1340                binarize && is_binarizable && !prebinarized,
1341            ) {
1342                let data = b
1343                    .binarize(&path, directory, &prefix, warnings)
1344                    .prepend_error(format!(
1345                        "Failed to binarize {}:",
1346                        printable(&relative.display().to_string())
1347                    ))?;
1348
1349                files.insert(name, Cursor::new(data.into_boxed_slice()));
1350            } else {
1351                if binarize
1352                    && is_binarizable
1353                    && !prebinarized
1354                    && binarizer.is_none()
1355                    && !cfg!(windows)
1356                {
1357                    warnings.warn(
1358                        Warning::new(
1359                            Some("non-windows-binarization"),
1360                            "On non-Windows systems binarize.exe is only used with --proton-binarize; file will be copied as-is.",
1361                        )
1362                        .in_file(relative.to_string_lossy()),
1363                    );
1364                }
1365
1366                let mut buffer: Vec<u8> = Vec::new();
1367                file.read_to_end(&mut buffer)
1368                    .prepend_error(format!("Failed to read \"{shown}\":"))?;
1369
1370                files.insert(name, Cursor::new(buffer.into_boxed_slice()));
1371            }
1372        }
1373
1374        if !header_extensions.contains_key("prefix") {
1375            let prefix: String = default_prefix(directory).ok_or_else(|| {
1376                error!(
1377                    "Invalid addon directory \"{}\".",
1378                    printable(&directory.display().to_string())
1379                )
1380            })?;
1381            header_extensions.insert("prefix".to_string(), prefix);
1382        }
1383
1384        for (key, value) in &options.header_extensions {
1385            set_extension(&mut header_extensions, key, value.clone());
1386        }
1387
1388        Ok(PBO {
1389            files,
1390            header_extensions,
1391            raw_names: HashMap::new(),
1392            raw_pairs: Vec::new(),
1393            headers: Vec::new(),
1394            checksum: None,
1395            computed_checksum: None,
1396        })
1397    }
1398
1399    /// Writes PBO to output.
1400    ///
1401    /// # Errors
1402    ///
1403    /// Returns an error on I/O failure, if an entry is too large, or if a header extension key
1404    /// or value contains a NUL byte.
1405    pub fn write<O: Write>(&self, output: &mut O) -> Result<(), Error> {
1406        self.write_with_checksum(output).map(|_| ())
1407    }
1408
1409    /// Writes the PBO and returns the SHA-1 it ends with.
1410    fn write_with_checksum<O: Write>(&self, output: &mut O) -> Result<Vec<u8>, Error> {
1411        let mut headers: Cursor<Vec<u8>> = Cursor::new(Vec::new());
1412
1413        let ext_header = PBOHeader {
1414            filename: String::new(),
1415            raw_filename: None,
1416            packing_method: 0x5665_7273,
1417            original_size: 0,
1418            reserved: 0,
1419            timestamp: 0,
1420            data_size: 0,
1421        };
1422        ext_header.write(&mut headers)?;
1423
1424        if let Some(prefix) = self.prefix_bytes() {
1425            headers.write_all(b"prefix\0")?;
1426            headers
1427                .write_cstring(prefix)
1428                .prepend_error("Header extension \"prefix\":")?;
1429        }
1430
1431        for ((key, _), (key_bytes, value_bytes)) in
1432            self.header_extensions().zip(self.header_extensions_bytes())
1433        {
1434            if key == "prefix" {
1435                continue;
1436            }
1437
1438            headers
1439                .write_cstring(key_bytes)
1440                .and_then(|()| headers.write_cstring(value_bytes))
1441                .prepend_error(format!("Header extension \"{}\":", printable(key)))?;
1442        }
1443        headers.write_cstring(String::new())?;
1444
1445        let mut files_sorted: Vec<(&str, &Cursor<Box<[u8]>>)> =
1446            self.files.iter().map(|(a, b)| (a.as_str(), b)).collect();
1447        files_sorted.sort_by_cached_key(|f| self.name_bytes(f.0).to_ascii_lowercase());
1448
1449        for (name, cursor) in &files_sorted {
1450            let size = u32::try_from(cursor.get_ref().len())
1451                .map_err(|_| error!("PBO entry \"{}\" is too large.", printable(name)))?;
1452            // an entry that was read and not replaced since keeps its packing method (compressed or
1453            // one we do not know): `files` holds its stored bytes, so the header must still say
1454            // how to decode them
1455            let kept = self
1456                .headers
1457                .iter()
1458                .rfind(|h| h.filename == *name)
1459                .filter(|h| h.packing_method != 0);
1460            let header = PBOHeader {
1461                filename: (*name).to_string(),
1462                raw_filename: self.raw_names.get(*name).cloned(),
1463                packing_method: kept.map_or(0, |h| h.packing_method),
1464                original_size: kept.map_or(size, |h| h.original_size),
1465                reserved: 0,
1466                timestamp: 0,
1467                data_size: size,
1468            };
1469
1470            header.write(&mut headers)?;
1471        }
1472
1473        let header = PBOHeader {
1474            packing_method: 0,
1475            ..ext_header
1476        };
1477        header.write(&mut headers)?;
1478
1479        let mut h = Sha1::new();
1480
1481        output.write_all(headers.get_ref())?;
1482        h.update(headers.get_ref());
1483
1484        for (_, cursor) in &files_sorted {
1485            output.write_all(cursor.get_ref())?;
1486            h.update(cursor.get_ref());
1487        }
1488
1489        output.write_all(&[0])?;
1490        let checksum = h.finalize();
1491        output.write_all(&checksum)?;
1492
1493        Ok(checksum.to_vec())
1494    }
1495
1496    /// Returns the contents of a file, decompressing it if the PBO stores it compressed.
1497    /// `files` keeps the stored bytes, because signing hashes those.
1498    ///
1499    /// # Errors
1500    ///
1501    /// Returns an error if a compressed entry cannot be decompressed.
1502    pub fn file_data(&self, name: &str) -> Result<Option<Vec<u8>>, Error> {
1503        let Some(cursor) = self.files.get(name) else {
1504            return Ok(None);
1505        };
1506
1507        // duplicate names: `files` kept the last value, so use the last header
1508        match self.headers.iter().rfind(|h| h.filename == name) {
1509            Some(h) if h.packing_method == PACKING_COMPRESSED => {
1510                lzss_decompress(cursor.get_ref(), h.original_size as usize)
1511                    .prepend_error(format!("Failed to decompress \"{}\":", printable(name)))
1512                    .map(Some)
1513            }
1514            _ => Ok(Some(cursor.get_ref().to_vec())),
1515        }
1516    }
1517
1518    /// Returns the PBO as a `Cursor`.
1519    ///
1520    /// # Errors
1521    ///
1522    /// Returns an error if the PBO cannot be written.
1523    pub fn to_cursor(&self) -> Result<Cursor<Vec<u8>>, Error> {
1524        let mut cursor: Cursor<Vec<u8>> = Cursor::new(Vec::new());
1525        self.write(&mut cursor)?;
1526
1527        cursor.seek(SeekFrom::Start(0))?;
1528
1529        Ok(cursor)
1530    }
1531}
1532
1533fn list_files(directory: &Path, excluded: &[Excluded]) -> Result<Vec<PathBuf>, Error> {
1534    let mut files: Vec<PathBuf> = Vec::new();
1535
1536    // read_dir order depends on the file system; sort by file name so warnings come in a fixed order
1537    let mut paths = read_dir(directory)?
1538        .map(|entry| entry.map(|e| e.path()))
1539        .collect::<Result<Vec<PathBuf>, _>>()?;
1540    paths.sort_by(|a, b| a.file_name().cmp(&b.file_name()));
1541
1542    for path in paths {
1543        if path.is_dir() {
1544            for f in list_files(&path, excluded)? {
1545                files.push(f);
1546            }
1547        } else if !is_excluded(&path, excluded) {
1548            files.push(path);
1549        }
1550    }
1551
1552    Ok(files)
1553}
1554
1555/// The entry names a source file packs as in `build`: the name before the `.p3do` rename (what `-x`
1556/// matches), the final one, and whether the entry is generated from source (the rapified
1557/// `config.cpp`, a `.p3do` packed as `.p3d`).
1558fn entry_name(relative: &Path, binarize: bool) -> (String, String, bool) {
1559    let mut relative = relative.to_path_buf();
1560    let mut generated = false;
1561    if binarize && relative.file_name() == Some(OsStr::new("config.cpp")) {
1562        relative = relative.with_file_name("config.bin");
1563        generated = true;
1564    }
1565    let pre = relative.to_string_lossy().replace('/', "\\");
1566    let name = if P3DO_RE.is_match(&pre) {
1567        generated = true;
1568        P3DO_RE.replace(&pre, ".p3d").into_owned()
1569    } else {
1570        pre.clone()
1571    };
1572    (pre, name, generated)
1573}
1574
1575/// Whether a path component names a Windows device (`CON`, `NUL.txt`, `COM1`, `COM\u{b9}`, `LPT0`, `CONIN$`,
1576/// ...), which Windows opens instead of a file whatever the extension and case.
1577#[must_use]
1578pub fn is_device_name(component: &str) -> bool {
1579    let stem = component
1580        .split('.')
1581        .next()
1582        .unwrap_or_default()
1583        .trim_end_matches(' ')
1584        .to_ascii_uppercase();
1585    matches!(
1586        stem.as_str(),
1587        "CON" | "PRN" | "AUX" | "NUL" | "CONIN$" | "CONOUT$"
1588    ) || ["COM", "LPT"].iter().any(|p| {
1589        stem.strip_prefix(p).is_some_and(|n| {
1590            let mut chars = n.chars();
1591            matches!(
1592                (chars.next(), chars.next()),
1593                (Some('0'..='9' | '\u{b9}' | '\u{b2}' | '\u{b3}'), None)
1594            )
1595        })
1596    })
1597}
1598
1599/// Maps an untrusted PBO entry name or prefix to a relative path that cannot leave the folder it
1600/// is joined to.
1601///
1602/// The name is split on `\` and `/`. Returns `None` if any component is empty (a leading,
1603/// trailing or doubled separator, so an absolute name is never accepted), is `.` or `..`, consists
1604/// only of dots and spaces, is a Windows device name, or contains `:` (drive letters), a NUL or any
1605/// control character (C0, DEL and C1, `char::is_control`), or if the name is empty.
1606#[must_use]
1607pub fn safe_relative_path(name: &str) -> Option<PathBuf> {
1608    let mut path = PathBuf::new();
1609    for component in name.split(['\\', '/']) {
1610        if component.is_empty()
1611            || is_device_name(component)
1612            || component.chars().all(|c| c == '.' || c == ' ')
1613            || component.chars().any(|c| c == ':' || c.is_control())
1614        {
1615            return None;
1616        }
1617        path.push(component);
1618    }
1619    if path.as_os_str().is_empty() {
1620        None
1621    } else {
1622        Some(path)
1623    }
1624}
1625
1626/// Returns true if `base` joined with `relative` would pass through an existing symlink
1627/// (checking every component below `base`, including the final one), or if that cannot be
1628/// determined.
1629fn crosses_symlink(base: &Path, relative: &Path) -> bool {
1630    let mut current = base.to_path_buf();
1631    for component in relative.components() {
1632        current.push(component);
1633        match current.symlink_metadata() {
1634            Ok(meta) if meta.file_type().is_symlink() => return true,
1635            Ok(_) => {}
1636            // nothing exists from here on, so nothing below can be a symlink
1637            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return false,
1638            // the path cannot be inspected (permissions, I/O error): do not assume it is safe
1639            Err(_) => return true,
1640        }
1641    }
1642    false
1643}
1644
1645/// The prefix of an addon folder without `$PBOPREFIX$`: its own name (a symlink keeps the name it is
1646/// reached by), or for `.`, `./` and `..` the name of the real folder.
1647fn default_prefix(directory: &Path) -> Option<String> {
1648    let name = |p: &Path| p.file_name().map(|n| n.to_string_lossy().into_owned());
1649    name(directory).or_else(|| directory.canonicalize().ok().and_then(|d| name(&d)))
1650}
1651
1652/// Replaces control characters (line breaks included) with a space.
1653fn sanitize_header(text: &str) -> String {
1654    text.chars()
1655        .map(|c| if c.is_control() { ' ' } else { c })
1656        .collect()
1657}
1658
1659/// Writes `$PBOPREFIX$` into `base` with control characters removed from keys and values, unless
1660/// it is a symlink.
1661fn write_prefix_file(
1662    extensions: &LinkedHashMap<String, String>,
1663    base: &Path,
1664    warnings: &mut dyn WarningSink,
1665) -> Result<(), Error> {
1666    let prefix_path = base.join("$PBOPREFIX$");
1667    if crosses_symlink(base, Path::new("$PBOPREFIX$")) {
1668        warnings.warn(Warning::new(
1669            Some("unsafe-path"),
1670            "Not writing $PBOPREFIX$: it is a symlink.",
1671        ));
1672        return Ok(());
1673    }
1674    let mut prefix_file =
1675        File::create(prefix_path).prepend_error("Failed to create prefix file:")?;
1676
1677    for (key, value) in extensions {
1678        let clean_key = sanitize_header(key);
1679        let clean_value = sanitize_header(value);
1680        if clean_key != *key || clean_value != *value {
1681            warnings.warn(Warning::new(Some("unsafe-header"), format!(
1682                    "Header extension {key:?} contains control characters; replaced them with spaces."
1683                )));
1684        }
1685        prefix_file
1686            .write_all(format!("{clean_key}={clean_value}\n").as_bytes())
1687            .prepend_error("Failed to write prefix file:")?;
1688    }
1689    Ok(())
1690}
1691
1692/// The relative path an unpacked entry is written to, and whether leading separators were
1693/// stripped from its name (`\scripts\x.c` is written as `scripts/x.c`). Everything else
1694/// [`safe_relative_path`] rejects stays rejected.
1695pub(crate) fn unpack_relative(name: &str) -> Option<(PathBuf, bool)> {
1696    let stripped = name.trim_start_matches(['\\', '/']);
1697    safe_relative_path(stripped).map(|relative| (relative, stripped.len() != name.len()))
1698}
1699
1700/// Warns that an entry name starts with a separator that was stripped.
1701pub(crate) fn warn_leading_separator(name: &str, relative: &Path, warnings: &mut dyn WarningSink) {
1702    warnings.warn(Warning::new(
1703        Some("leading-separator"),
1704        format!(
1705            "Entry \"{}\" starts with a path separator; extracting it as \"{}\".",
1706            printable(name),
1707            printable(&relative.to_string_lossy())
1708        ),
1709    ));
1710}
1711
1712/// The folder, relative to the output folder, a PBO with this `prefix` is unpacked into: `None` for no
1713/// prefix, an empty one or one of only separators.
1714///
1715/// # Errors
1716///
1717/// Returns an error if the prefix is not a safe relative path.
1718pub(crate) fn prefix_relative(prefix: Option<&str>) -> Result<Option<PathBuf>, Error> {
1719    match prefix {
1720        Some(prefix) if prefix.split(['\\', '/']).all(str::is_empty) => Ok(None),
1721        Some(prefix) => {
1722            // other tools may write a trailing separator; a leading or doubled one is rejected
1723            safe_relative_path(prefix.trim_end_matches(['\\', '/']))
1724                .map(Some)
1725                .ok_or_else(|| error!("Unsafe PBO prefix {prefix:?}; refusing to unpack."))
1726        }
1727        None => Ok(None),
1728    }
1729}
1730
1731/// The folder a PBO is unpacked into: `output`, or with `use_prefix` `<output>/<prefix>`. An empty
1732/// prefix (or one of only separators) means no prefix.
1733fn unpack_base(pbo: &PBO, output: &Path, use_prefix: bool) -> Result<PathBuf, Error> {
1734    if !use_prefix {
1735        return Ok(output.to_path_buf());
1736    }
1737    let prefix = pbo.header_extensions.get("prefix").map(String::as_str);
1738    match prefix_relative(prefix)? {
1739        None => Ok(output.to_path_buf()),
1740        Some(relative) => {
1741            if crosses_symlink(output, &relative) {
1742                return Err(error!(
1743                    "PBO prefix {prefix:?} goes through a symlink; refusing to unpack."
1744                ));
1745            }
1746            Ok(output.join(relative))
1747        }
1748    }
1749}
1750
1751/// How [`unpack`] treats existing files and the PBO prefix.
1752#[derive(Debug, Clone, Default)]
1753#[non_exhaustive]
1754pub struct UnpackOptions {
1755    /// Overwrite existing files instead of failing.
1756    pub force: bool,
1757    /// Extract into `<target>/<prefix>/` instead of `<target>/`.
1758    pub use_prefix: bool,
1759    /// Glob patterns of entries to leave out; see [`EntryFilter`]. An entry that matches one is
1760    /// never written, even when it matches `only`.
1761    pub exclude: Vec<String>,
1762    /// Glob patterns of the entries to write; see [`EntryFilter`]. Empty means every entry.
1763    pub only: Vec<String>,
1764}
1765
1766/// Selects PBO entries by glob pattern: an entry passes when it matches at least one `only` pattern (or
1767/// `only` is empty) and no `exclude` pattern.
1768///
1769/// `*` stands for any run of characters, as in the `-x` patterns of `pack`. The name is matched with
1770/// `/` separators (a `\` is turned into `/`), without the PBO prefix, and ignoring case, like PBO names.
1771#[derive(Debug, Clone, Default)]
1772#[non_exhaustive]
1773pub struct EntryFilter {
1774    only: Vec<String>,
1775    exclude: Vec<String>,
1776}
1777
1778impl EntryFilter {
1779    /// A filter for the `only` and `exclude` patterns. The patterns are normalised once (lowercase,
1780    /// `\` turned into `/`).
1781    #[must_use]
1782    pub fn new(only: Vec<String>, exclude: Vec<String>) -> Self {
1783        let normalise = |patterns: Vec<String>| {
1784            patterns
1785                .into_iter()
1786                .map(|p| p.replace('\\', "/").to_lowercase())
1787                .collect()
1788        };
1789        Self {
1790            only: normalise(only),
1791            exclude: normalise(exclude),
1792        }
1793    }
1794
1795    /// Whether the entry `name` passes the filter.
1796    #[must_use]
1797    pub fn matches(&self, name: &str) -> bool {
1798        let name = name.replace('\\', "/").to_lowercase();
1799        let hit = |pattern: &String| matches_glob(&name, pattern);
1800        (self.only.is_empty() || self.only.iter().any(hit)) && !self.exclude.iter().any(hit)
1801    }
1802}
1803
1804/// Fails when a selected file of `pbo` (or `$PBOPREFIX$`) already exists below `base`. Runs before anything
1805/// is written, so a conflict leaves the target untouched.
1806fn check_unpack_conflicts(pbo: &PBO, base: &Path, filter: &EntryFilter) -> Result<(), Error> {
1807    let prefix = (!pbo.header_extensions.is_empty()).then_some("$PBOPREFIX$");
1808    let first = prefix
1809        .into_iter()
1810        .chain(
1811            pbo.files
1812                .keys()
1813                .map(String::as_str)
1814                .filter(|name| filter.matches(name)),
1815        )
1816        .find(|name| {
1817            unpack_relative(name).is_some_and(|(relative, _)| {
1818                !crosses_symlink(base, &relative) && base.join(relative).exists()
1819            })
1820        });
1821    match first {
1822        Some(name) => Err(error!(
1823            "Target folder \"{}\" already contains files of this PBO (first: \"{}\"). Use --force to overwrite.",
1824            printable(&base.display().to_string()),
1825            printable(name)
1826        )),
1827        None => Ok(()),
1828    }
1829}
1830
1831/// Unpacks a PBO into the target folder.
1832///
1833/// Entry names and the prefix come from the (untrusted) PBO: entries whose name does not map to a
1834/// safe relative path, that would be written through a symlink, or that collide (case-insensitively)
1835/// with an entry already written in this run are skipped with a warning. Leading separators are
1836/// stripped from a name (`leading-separator` warning). With `options.use_prefix`
1837/// the files are extracted into `<target>/<prefix>/`; an empty prefix means no prefix. `options.only` and
1838/// `options.exclude` select the entries to write (`$PBOPREFIX$` is always written).
1839///
1840/// # Errors
1841///
1842/// Returns an error if the PBO cannot be read, the prefix is unsafe with `use_prefix`, or, without
1843/// `options.force`, a selected file of the PBO (or `$PBOPREFIX$`) already exists in the target. That
1844/// check covers the selected entries plus `$PBOPREFIX$` and runs before anything is written, so a
1845/// conflict leaves the target untouched.
1846pub fn unpack<I: Read>(
1847    input: &mut I,
1848    target: &Path,
1849    options: &UnpackOptions,
1850    warnings: &mut dyn WarningSink,
1851) -> Result<(), Error> {
1852    let UnpackOptions {
1853        force,
1854        use_prefix,
1855        ref exclude,
1856        ref only,
1857    } = *options;
1858    let filter = EntryFilter::new(only.clone(), exclude.clone());
1859    let output = target;
1860    let pbo = PBO::read(input).prepend_error("Failed to read PBO:")?;
1861
1862    let base = unpack_base(&pbo, output, use_prefix)?;
1863
1864    if !force {
1865        check_unpack_conflicts(&pbo, &base, &filter)?;
1866    }
1867
1868    create_dir_all(&base).prepend_error("Failed to create output folder:")?;
1869
1870    if !pbo.header_extensions.is_empty() {
1871        write_prefix_file(&pbo.header_extensions, &base, warnings)?;
1872    }
1873
1874    let mut written: HashSet<String> = HashSet::new();
1875    for file_name in pbo.files.keys() {
1876        if !filter.matches(file_name) {
1877            continue;
1878        }
1879        if pbo.raw_names.contains_key(file_name) {
1880            warnings.warn(Warning::new(
1881                Some("non-utf8-filename"),
1882                format!(
1883                    "Entry name {file_name:?} is not valid UTF-8; extracting it as windows-1252."
1884                ),
1885            ));
1886        }
1887        let Some((relative, stripped)) = unpack_relative(file_name) else {
1888            warnings.warn(Warning::new(
1889                Some("unsafe-path"),
1890                format!("Skipping \"{}\": unsafe path.", printable(file_name)),
1891            ));
1892            continue;
1893        };
1894        let key = relative.to_string_lossy().to_lowercase();
1895        if written.contains(&key) {
1896            warnings.warn(Warning::new(
1897                Some("duplicate-entry"),
1898                format!(
1899                    "Skipping \"{}\": an entry with the same path was already extracted.",
1900                    printable(file_name)
1901                ),
1902            ));
1903            continue;
1904        }
1905        if crosses_symlink(&base, &relative) {
1906            warnings.warn(Warning::new(
1907                Some("unsafe-path"),
1908                format!(
1909                    "Skipping \"{}\": the target path goes through a symlink.",
1910                    printable(file_name)
1911                ),
1912            ));
1913            continue;
1914        }
1915        let data = match pbo.file_data(file_name) {
1916            Ok(Some(data)) => data,
1917            Ok(None) => continue,
1918            Err(e) => {
1919                warnings.warn(Warning::new(
1920                    None,
1921                    format!("Skipping \"{}\": {e}", printable(file_name)),
1922                ));
1923                continue;
1924            }
1925        };
1926        if stripped {
1927            warn_leading_separator(file_name, &relative, warnings);
1928        }
1929        let path = base.join(&relative);
1930        written.insert(key);
1931        let written_ok = create_dir_all(path.parent().unwrap_or(&base))
1932            .prepend_error("Failed to create output folder:")
1933            .and_then(|()| File::create(&path).prepend_error("Failed to open output file:"))
1934            .and_then(|mut file| {
1935                file.write_all(&data)
1936                    .prepend_error("Failed to write output file:")
1937            });
1938        if let Err(e) = written_ok {
1939            warnings.warn(Warning::new(
1940                None,
1941                format!("Skipping \"{}\": {e}", printable(file_name)),
1942            ));
1943        }
1944    }
1945
1946    Ok(())
1947}
1948
1949#[cfg(test)]
1950mod tests {
1951    /// #62: the full list of Windows device names, in any case, with and without an extension.
1952    #[test]
1953    fn device_names_are_complete() {
1954        for name in [
1955            "CON",
1956            "PRN",
1957            "AUX",
1958            "NUL",
1959            "COM0",
1960            "COM1",
1961            "COM9",
1962            "LPT0",
1963            "LPT1",
1964            "LPT9",
1965            "COM\u{b9}",
1966            "COM\u{b2}",
1967            "COM\u{b3}",
1968            "LPT\u{b9}",
1969            "LPT\u{b2}",
1970            "LPT\u{b3}",
1971            "CONIN$",
1972            "CONOUT$",
1973        ] {
1974            for variant in [
1975                name.to_string(),
1976                name.to_lowercase(),
1977                format!("{name}.txt"),
1978                format!("{}.cfg", name.to_lowercase()),
1979                format!("{name} .x"),
1980            ] {
1981                assert!(super::is_device_name(&variant), "{variant}");
1982                assert!(
1983                    super::safe_relative_path(&format!("a\\{variant}")).is_none(),
1984                    "{variant}"
1985                );
1986            }
1987        }
1988        for name in [
1989            "COM",
1990            "COM10",
1991            "COM\u{b9}\u{b9}",
1992            "CONIN",
1993            "CONOUT",
1994            "CONIN$$",
1995            "LPT",
1996            "COMA",
1997            "ACON",
1998            "x.CON",
1999        ] {
2000            assert!(!super::is_device_name(name), "{name}");
2001        }
2002    }
2003
2004    use super::*;
2005
2006    fn p(s: &str) -> Option<PathBuf> {
2007        safe_relative_path(s)
2008    }
2009
2010    #[test]
2011    fn glob_matches_without_panicking() {
2012        assert!(matches_glob("", "*"));
2013        assert!(!matches_glob("ab", "abc*"));
2014        assert!(!matches_glob("é", "*x"));
2015        assert!(matches_glob("abc", "a*c"));
2016        assert!(matches_glob("abc", "*"));
2017        assert!(matches_glob("abc", "abc"));
2018        assert!(!matches_glob("abd", "abc"));
2019        assert!(matches_glob("a.bin", "*.bin"));
2020        assert!(matches_glob("aXbYc", "a*b*c"));
2021    }
2022
2023    #[test]
2024    fn lzss_size_bomb_is_an_error() {
2025        let err = lzss_decompress(&[0xFF; 16], 0xFFFF_FFF0).unwrap_err();
2026        assert!(err.to_string().contains("implausible"), "{err}");
2027        assert!(lzss_decompress(&[0xFF, b'a'], 9).is_err());
2028    }
2029
2030    #[test]
2031    fn safe_path_accepts_normal_names() {
2032        assert_eq!(
2033            p("a\\b/c.txt"),
2034            Some(PathBuf::from("a").join("b").join("c.txt"))
2035        );
2036        assert_eq!(
2037            p("a.b\\.hidden"),
2038            Some(PathBuf::from("a.b").join(".hidden"))
2039        );
2040    }
2041
2042    #[test]
2043    fn safe_path_rejects_empty_components() {
2044        for bad in [
2045            "\\abs.txt",
2046            "/abs",
2047            "\\abs",
2048            "/tmp//x",
2049            "a\\\\b",
2050            "a\\b\\",
2051            "a/",
2052            "\\\\?\\x",
2053        ] {
2054            assert_eq!(p(bad), None, "{bad:?}");
2055        }
2056    }
2057
2058    #[test]
2059    fn safe_path_rejects_dots_and_spaces() {
2060        for bad in [
2061            "..",
2062            "a\\..\\b",
2063            "a\\.\\b",
2064            "a\\...\\b",
2065            "a\\. \\b",
2066            "a\\ \\b",
2067            "a\\.. ",
2068        ] {
2069            assert_eq!(p(bad), None, "{bad:?}");
2070        }
2071    }
2072
2073    #[test]
2074    fn safe_path_rejects_colon_nul_and_control() {
2075        for bad in [
2076            "C:\\x.txt",
2077            "a:b",
2078            "a\0b",
2079            "a\nb",
2080            "a\tb",
2081            "a\x7fb",
2082            "a\u{80}b",
2083            "a\u{9b}b",
2084            "a\u{9f}",
2085        ] {
2086            assert_eq!(p(bad), None, "{bad:?}");
2087        }
2088    }
2089
2090    #[cfg(unix)]
2091    #[test]
2092    fn crosses_symlink_fails_closed_when_the_path_cannot_be_inspected() {
2093        use std::os::unix::fs::PermissionsExt;
2094
2095        let dir = tempfile::tempdir().unwrap();
2096        let locked = dir.path().join("locked");
2097        std::fs::create_dir(&locked).unwrap();
2098        std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o000)).unwrap();
2099        // root ignores permissions, so there is nothing to test
2100        let permissions_ignored = locked
2101            .join("x")
2102            .symlink_metadata()
2103            .is_err_and(|e| e.kind() == std::io::ErrorKind::NotFound);
2104        let crosses = crosses_symlink(dir.path(), Path::new("locked/x"));
2105        std::fs::set_permissions(&locked, std::fs::Permissions::from_mode(0o700)).unwrap();
2106        if !permissions_ignored {
2107            assert!(crosses, "an unreadable path must count as unsafe");
2108        }
2109    }
2110
2111    #[test]
2112    fn safe_path_rejects_windows_device_names() {
2113        for bad in ["con", "a\\NUL.txt", "Aux.tar.gz", "com1", "LPT9.x", "prn."] {
2114            assert_eq!(p(bad), None, "{bad:?}");
2115        }
2116        for fine in ["console", "com10", "nulls.txt", "a.con"] {
2117            assert!(p(fine).is_some(), "{fine:?}");
2118        }
2119    }
2120
2121    #[test]
2122    fn safe_path_rejects_empty() {
2123        for bad in ["", "\\", "/\\/"] {
2124            assert_eq!(p(bad), None, "{bad:?}");
2125        }
2126    }
2127}