Skip to main content

dayzmake_core/
extract.rs

1//! Extracts a whole DayZ install, a mod or a single PBO into one tree organised by prefix.
2//!
3//! The tree is written to a staging folder next to the target and swapped in with a rename when
4//! everything succeeded, so a failed or repeated run never leaves a half-written or stale tree. The
5//! entry names, prefixes and PBO files are untrusted: names are validated like [`crate::pbo::unpack`]
6//! does and the offenders are skipped with a warning.
7
8use std::collections::BTreeMap;
9use std::fs::{self, File};
10use std::io::{self, BufReader, Cursor, Error, ErrorKind, Read, Seek, SeekFrom};
11use std::path::{Path, PathBuf};
12
13use crate::config::{Config, WriteOptions, is_rapified};
14use crate::error::{ErrorExt, printable};
15use crate::pbo::{
16    EntryFilter, IndexEntry, decompress_entry, prefix_relative, read_index, safe_relative_path,
17    unpack_relative, warn_leading_separator,
18};
19use crate::warning::{Warning, WarningSink};
20
21/// The file in the target that maps every prefix to its PBO.
22const MAP_FILE: &str = "pbo-map.tsv";
23
24/// What [`extract`] does.
25#[derive(Debug, Clone, Default)]
26#[non_exhaustive]
27pub struct ExtractOptions {
28    /// Replace an existing target folder instead of failing.
29    pub force: bool,
30    /// Write every rapified `*.bin` as text, with the extension `.cpp`.
31    pub derapify: bool,
32    /// Glob patterns of entries to leave out; see [`EntryFilter`].
33    pub exclude: Vec<String>,
34    /// Glob patterns of the entries to write; see [`EntryFilter`]. Empty means every entry.
35    pub only: Vec<String>,
36}
37
38/// What [`extract`] wrote.
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40#[non_exhaustive]
41pub struct ExtractSummary {
42    pbos: usize,
43    files: usize,
44}
45
46impl ExtractSummary {
47    /// The number of PBOs that were read.
48    #[must_use]
49    pub fn pbos(&self) -> usize {
50        self.pbos
51    }
52
53    /// The number of files in the tree, without the PBO map.
54    #[must_use]
55    pub fn files(&self) -> usize {
56        self.files
57    }
58}
59
60/// A PBO of the source: its path and its path relative to the source with `/` separators.
61struct SourcePbo {
62    path: PathBuf,
63    relative: String,
64}
65
66/// Removes the staging folder unless it was handed over.
67struct Staging {
68    path: PathBuf,
69    armed: bool,
70}
71
72impl Drop for Staging {
73    fn drop(&mut self) {
74        if self.armed {
75            // best effort on the way out: the error that got us here matters more
76            let _ = fs::remove_dir_all(&self.path);
77        }
78    }
79}
80
81fn is_dir(path: &Path) -> bool {
82    fs::metadata(path).is_ok_and(|m| m.is_dir())
83}
84
85/// The PBOs of `source`, in sorted path order: the file itself, or the `*.pbo` files directly in the
86/// `dta` and `addons` folders of a folder (any case).
87fn find_pbos(source: &Path) -> Result<Vec<SourcePbo>, Error> {
88    let shown = printable(&source.display().to_string());
89    let meta = fs::metadata(source).prepend_error(format!("Failed to read source \"{shown}\":"))?;
90    let mut found = Vec::new();
91    if meta.is_file() {
92        let name = source
93            .file_name()
94            .map_or_else(String::new, |n| n.to_string_lossy().into_owned());
95        found.push(SourcePbo {
96            path: source.to_path_buf(),
97            relative: name,
98        });
99        return Ok(found);
100    }
101    let read = |dir: &Path| {
102        fs::read_dir(dir).prepend_error(format!(
103            "Failed to read folder \"{}\":",
104            printable(&dir.display().to_string())
105        ))
106    };
107    for folder in read(source)? {
108        let folder = folder.prepend_error(format!("Failed to read folder \"{shown}\":"))?;
109        let folder_name = folder.file_name().to_string_lossy().into_owned();
110        let lower = folder_name.to_lowercase();
111        if (lower != "dta" && lower != "addons") || !is_dir(&folder.path()) {
112            continue;
113        }
114        for file in read(&folder.path())? {
115            let file = file.prepend_error("Failed to read folder entry:")?;
116            let path = file.path();
117            let is_pbo = path
118                .extension()
119                .is_some_and(|e| e.eq_ignore_ascii_case("pbo"));
120            if is_pbo && fs::metadata(&path).is_ok_and(|m| m.is_file()) {
121                found.push(SourcePbo {
122                    relative: format!("{folder_name}/{}", file.file_name().to_string_lossy()),
123                    path,
124                });
125            }
126        }
127    }
128    found.sort_by(|a, b| a.relative.cmp(&b.relative));
129    if found.is_empty() {
130        return Err(error!(
131            "Found no PBOs in the dta or addons folder of \"{shown}\"."
132        ));
133    }
134    Ok(found)
135}
136
137/// Whether `folder` is empty or holds the `pbo-map.tsv` of an earlier run, so that replacing it cannot
138/// destroy anything but an extract result.
139fn looks_like_extract_result(folder: &Path) -> bool {
140    let is_empty = fs::read_dir(folder).is_ok_and(|mut entries| entries.next().is_none());
141    is_empty || fs::symlink_metadata(folder.join(MAP_FILE)).is_ok_and(|m| m.is_file())
142}
143
144/// `path` with symlinks resolved as far as it exists: the nearest existing ancestor is canonicalized and the
145/// missing rest appended. `None` if the missing rest has a `..` or a root, which cannot be resolved by name.
146fn resolve_for_comparison(path: &Path) -> Option<PathBuf> {
147    let mut existing = path.to_path_buf();
148    let mut rest = Vec::new();
149    let mut resolved = loop {
150        if existing.as_os_str().is_empty() {
151            existing = PathBuf::from(".");
152        }
153        if let Ok(done) = existing.canonicalize() {
154            break done;
155        }
156        rest.push(existing.file_name()?.to_os_string());
157        if !existing.pop() {
158            return None;
159        }
160    };
161    resolved.extend(rest.iter().rev());
162    Some(resolved)
163}
164
165/// Checks the target before anything is written: an existing one needs `force`, must be a real folder
166/// that is empty or an earlier result, and must neither contain nor lie inside the source.
167fn check_target(
168    sources: &[SourcePbo],
169    source: &Path,
170    target: &Path,
171    force: bool,
172) -> Result<(), Error> {
173    let shown = printable(&target.display().to_string());
174    match fs::symlink_metadata(target) {
175        Ok(meta) => {
176            if !meta.is_dir() {
177                return Err(error!("Target \"{shown}\" exists and is not a folder."));
178            }
179            if !force {
180                return Err(error!(
181                    "Target folder \"{shown}\" already exists. Use --force to replace it."
182                ));
183            }
184            // paths that cannot be compared count as overlapping: better refuse than delete the source
185            let outer = target.canonicalize();
186            let overlaps = |inner: &Path| match (&outer, inner.canonicalize()) {
187                (Ok(outer), Ok(inner)) => inner.starts_with(outer),
188                _ => true,
189            };
190            // `find_pbos` has just listed the source, so this fails only if it vanishes in between
191            let Ok(resolved_source) = source.canonicalize() else {
192                return Err(error!(
193                    "Cannot resolve the source folder \"{}\".",
194                    printable(&source.display().to_string())
195                ));
196            };
197            let inside = match &outer {
198                Ok(outer) => outer.starts_with(resolved_source),
199                Err(_) => true,
200            };
201            if inside {
202                return Err(error!(
203                    "Target folder \"{shown}\" is inside the source; refusing to replace it."
204                ));
205            }
206            if overlaps(source) || sources.iter().any(|s| overlaps(&s.path)) {
207                return Err(error!(
208                    "Target folder \"{shown}\" contains the source; refusing to replace it."
209                ));
210            }
211            if !looks_like_extract_result(target) {
212                return Err(error!(
213                    "Target folder \"{shown}\" is not empty and not the result of an earlier extract (it has no {MAP_FILE}); refusing to replace it."
214                ));
215            }
216            Ok(())
217        }
218        Err(e) if e.kind() == ErrorKind::NotFound => {
219            // a new target inside the source would write into it, and the next run with --force would
220            // refuse it: refuse before anything is created
221            let Some(resolved) = resolve_for_comparison(target) else {
222                return Err(error!(
223                    "Invalid target folder \"{shown}\": cannot resolve \"..\" after a folder that does not exist."
224                ));
225            };
226            // `find_pbos` has just listed the source, so this fails only if it vanishes in between
227            let Ok(source) = source.canonicalize() else {
228                return Err(error!(
229                    "Cannot resolve the source folder \"{}\".",
230                    printable(&source.display().to_string())
231                ));
232            };
233            if resolved.starts_with(source) {
234                return Err(error!(
235                    "Target folder \"{shown}\" is inside the source; refusing to replace it."
236                ));
237            }
238            Ok(())
239        }
240        Err(e) => Err(e).prepend_error(format!("Failed to read target \"{shown}\":")),
241    }
242}
243
244/// The final folder name of `target`; a target that ends in `..` or is a root has none and is refused.
245fn target_name(target: &Path) -> Result<String, Error> {
246    target
247        .file_name()
248        .map(|n| n.to_string_lossy().into_owned())
249        .ok_or_else(|| {
250            error!(
251                "Invalid target folder \"{}\".",
252                printable(&target.display().to_string())
253            )
254        })
255}
256
257/// Creates an empty staging folder next to `target` (same parent, so the final rename stays on one
258/// file system).
259fn create_staging(target: &Path) -> Result<Staging, Error> {
260    let name = target_name(target)?;
261    let parent = parent_of(target);
262    fs::create_dir_all(&parent).prepend_error("Failed to create the folder of the target:")?;
263    for attempt in 0..1000_u32 {
264        let path = parent.join(format!(".{name}.extract-{}-{attempt}", std::process::id()));
265        match fs::create_dir(&path) {
266            Ok(()) => return Ok(Staging { path, armed: true }),
267            Err(e) if e.kind() == ErrorKind::AlreadyExists => {}
268            Err(e) => return Err(e).prepend_error("Failed to create the staging folder:"),
269        }
270    }
271    Err(error!("Failed to find a free name for the staging folder."))
272}
273
274fn parent_of(path: &Path) -> PathBuf {
275    match path.parent() {
276        Some(p) if !p.as_os_str().is_empty() => p.to_path_buf(),
277        _ => PathBuf::from("."),
278    }
279}
280
281/// `data` as text if it is a rapified config.
282fn derapify(data: &[u8]) -> Result<Vec<u8>, Error> {
283    let config = Config::read_rapified(&mut Cursor::new(data))?;
284    let mut text = Vec::new();
285    config.write_with(&mut text, &WriteOptions::new())?;
286    Ok(text)
287}
288
289/// `bytes` with `\`, TAB, CR and LF escaped as `\\`, `\t`, `\r` and `\n`, so that every `\` of the output starts an
290/// escape.
291fn escape(bytes: &[u8], out: &mut Vec<u8>) {
292    for &b in bytes {
293        match b {
294            b'\\' => out.extend_from_slice(b"\\\\"),
295            b'\t' => out.extend_from_slice(b"\\t"),
296            b'\r' => out.extend_from_slice(b"\\r"),
297            b'\n' => out.extend_from_slice(b"\\n"),
298            _ => out.push(b),
299        }
300    }
301}
302
303/// The largest entry that is read into memory (compressed ones and derapify candidates); everything
304/// else is copied from the PBO to the file in pieces.
305const MAX_IN_MEMORY: u64 = 1 << 29;
306
307/// What an entry's file will hold.
308enum Content {
309    /// Copy this many bytes from the PBO, starting at the offset.
310    Stream {
311        offset: u64,
312        size: u64,
313    },
314    Bytes(Vec<u8>),
315}
316
317/// The state that spans all PBOs of one run.
318struct Run<'a> {
319    staging: &'a Path,
320    options: &'a ExtractOptions,
321    filter: EntryFilter,
322    /// The PBO paths, by index.
323    names: Vec<String>,
324    /// Lowercase relative path of every file written -> (path as written, index of its PBO).
325    owners: BTreeMap<String, (PathBuf, usize)>,
326    /// Prefix bytes and PBO path of every PBO.
327    map: Vec<(Vec<u8>, String)>,
328    files: usize,
329}
330
331impl Run<'_> {
332    /// The file already written that a new file at `relative` (lowercase `key`) cannot coexist with: one at
333    /// a parent folder's path, or one below `relative` as a folder. Its path, the index of its PBO and
334    /// whether it is the file at a parent folder (the new entry needs a folder there).
335    fn clash(&self, relative: &Path, key: &str) -> Option<(PathBuf, usize, bool)> {
336        for parent in relative.ancestors().skip(1) {
337            let parent = parent.to_string_lossy().to_lowercase();
338            if let Some((path, owner)) = self.owners.get(&parent) {
339                return Some((path.clone(), *owner, true));
340            }
341        }
342        let below = format!("{key}{}", std::path::MAIN_SEPARATOR);
343        let (found, (path, owner)) = self.owners.range(below.clone()..).next()?;
344        found
345            .starts_with(&below)
346            .then(|| (path.clone(), *owner, false))
347    }
348
349    /// Warns and returns `true` if the file at `relative` clashes with one written earlier, see [`Run::clash`].
350    fn skip_clash(
351        &self,
352        index: usize,
353        relative: &Path,
354        key: &str,
355        warnings: &mut dyn WarningSink,
356    ) -> bool {
357        let Some((other, owner, other_is_file)) = self.clash(relative, key) else {
358            return false;
359        };
360        let pbo_name = |i: usize| self.names.get(i).map_or("?", String::as_str);
361        // shown with `/` on every platform; the keys stay native paths
362        let shown = |p: &Path| {
363            let parts: Vec<_> = p
364                .components()
365                .map(|c| c.as_os_str().to_string_lossy())
366                .collect();
367            printable(&parts.join("/"))
368        };
369        let (pbo, other_pbo) = (printable(pbo_name(index)), printable(pbo_name(owner)));
370        // the existing file is at a parent folder of the new entry, or the new entry is a file where it has a folder
371        let message = if other_is_file {
372            format!(
373                "Skipping \"{}\" from {pbo}: it needs \"{}\" as a folder, but {other_pbo} has a file there.",
374                shown(relative),
375                shown(&other),
376            )
377        } else {
378            format!(
379                "Skipping \"{}\" from {pbo}: it is a file, but {other_pbo} has a folder there.",
380                shown(relative),
381            )
382        };
383        warnings.warn(Warning::new(Some("extract-path-clash"), message));
384        true
385    }
386
387    /// Extracts one PBO. A PBO that cannot be read or an entry that cannot be decompressed or written is
388    /// an error; unsafe names are skipped.
389    fn pbo(
390        &mut self,
391        index: usize,
392        source: &SourcePbo,
393        warnings: &mut dyn WarningSink,
394    ) -> Result<(), Error> {
395        let shown = printable(&source.relative);
396        let mut file = BufReader::new(
397            File::open(&source.path).prepend_error(format!("Failed to open PBO \"{shown}\":"))?,
398        );
399        let pbo_index =
400            read_index(&mut file).prepend_error(format!("Failed to read PBO \"{shown}\":"))?;
401
402        let stem = source
403            .path
404            .file_stem()
405            .map_or_else(String::new, |s| s.to_string_lossy().into_owned());
406        let prefix = pbo_index.prefix.as_deref();
407        let folder = match prefix_relative(prefix) {
408            Ok(Some(relative)) => Some(relative),
409            Ok(None) => safe_relative_path(&stem),
410            Err(_) => None,
411        };
412        let map_prefix = match (prefix_relative(prefix), pbo_index.prefix_bytes) {
413            (Ok(None), _) => stem.as_bytes().to_vec(),
414            (_, Some(raw)) => raw,
415            (_, None) => prefix.unwrap_or_default().as_bytes().to_vec(),
416        };
417        // `/` separators like the tree, so that the file needs no `\` of its own
418        let map_prefix: Vec<u8> = map_prefix
419            .iter()
420            .map(|&b| if b == b'\\' { b'/' } else { b })
421            .collect();
422        self.map.push((map_prefix, source.relative.clone()));
423        let folder = folder.filter(|f| {
424            !f.components().next().is_some_and(|c| {
425                c.as_os_str()
426                    .to_string_lossy()
427                    .eq_ignore_ascii_case(MAP_FILE)
428            })
429        });
430        let Some(folder) = folder else {
431            warnings.warn(Warning::new(
432                Some("unsafe-path"),
433                format!("Skipping PBO \"{shown}\": its prefix is not a safe folder name."),
434            ));
435            return Ok(());
436        };
437
438        for entry in &pbo_index.entries {
439            if !self.filter.matches(&entry.name) {
440                continue;
441            }
442            let end = entry.offset.checked_add(entry.size);
443            if end.is_none_or(|end| end > pbo_index.len) {
444                return Err(error!(
445                    "PBO \"{shown}\": entry \"{}\" is truncated (its data ends past the end of the file).",
446                    printable(&entry.name)
447                ));
448            }
449            self.entry(index, &folder, entry, &mut file, warnings)
450                .prepend_error(format!("PBO \"{shown}\":"))?;
451        }
452        Ok(())
453    }
454
455    /// Writes one entry below `folder`, or warns why it is skipped.
456    fn entry<F: Read + Seek>(
457        &mut self,
458        index: usize,
459        folder: &Path,
460        entry: &IndexEntry,
461        file: &mut F,
462        warnings: &mut dyn WarningSink,
463    ) -> Result<(), Error> {
464        let name = entry.name.as_str();
465        if entry.non_utf8 {
466            warnings.warn(Warning::new(
467                Some("non-utf8-filename"),
468                format!("Entry name {name:?} is not valid UTF-8; extracting it as windows-1252."),
469            ));
470        }
471        let Some((mut relative, stripped)) = unpack_relative(name) else {
472            warnings.warn(Warning::new(
473                Some("unsafe-path"),
474                format!("Skipping \"{}\": unsafe path.", printable(name)),
475            ));
476            return Ok(());
477        };
478        if stripped {
479            warn_leading_separator(name, &relative, warnings);
480        }
481        let is_bin = relative
482            .extension()
483            .is_some_and(|e| e.eq_ignore_ascii_case("bin"));
484        let fail = |what: &str| format!("{what} \"{}\":", printable(name));
485        let mut content = Content::Stream {
486            offset: entry.offset,
487            size: entry.size,
488        };
489        if entry.compressed {
490            if entry.size > MAX_IN_MEMORY || u64::from(entry.original_size) > MAX_IN_MEMORY {
491                return Err(error!(
492                    "Compressed entry \"{}\" is too large.",
493                    printable(name)
494                ));
495            }
496            let stored =
497                read_at(file, entry.offset, entry.size).prepend_error(fail("Failed to read"))?;
498            let data = decompress_entry(&stored, entry.original_size)
499                .prepend_error(fail("Failed to decompress"))?;
500            content = Content::Bytes(data);
501        }
502        if self.options.derapify && is_bin {
503            let (derapified, kept) = derapify_entry(entry, content, file, warnings)?;
504            if derapified {
505                relative = relative.with_extension("cpp");
506            }
507            content = kept;
508        }
509        let relative = folder.join(relative);
510        let key = relative.to_string_lossy().to_lowercase();
511        if self.skip_clash(index, &relative, &key, warnings) {
512            return Ok(()); // the clash is a warning, not an error
513        }
514        if let Some((old, owner)) = self.owners.get(&key).cloned() {
515            if owner == index {
516                warnings.warn(Warning::new(
517                    Some("duplicate-entry"),
518                    format!(
519                        "Skipping \"{}\": an entry with the same path was already extracted.",
520                        printable(name)
521                    ),
522                ));
523                return Ok(());
524            }
525            let pbo_name = |i: usize| self.names.get(i).map_or("?", String::as_str);
526            warnings.warn(Warning::new(
527                Some("duplicate-path"),
528                format!(
529                    "\"{}\" is in {} and in {}; keeping the one of {}.",
530                    printable(&relative.to_string_lossy()),
531                    printable(pbo_name(owner)),
532                    printable(pbo_name(index)),
533                    printable(pbo_name(index)),
534                ),
535            ));
536            // the file is replaced below; one that is already gone does not matter
537            let _ = fs::remove_file(self.staging.join(old));
538        }
539        let path = self.staging.join(&relative);
540        // the staging folder is new and holds nothing but what this run wrote, so no path in it is a symlink
541        if let Some(parent) = path.parent() {
542            fs::create_dir_all(parent).prepend_error(fail("Failed to create the folder of"))?;
543        }
544        match content {
545            Content::Bytes(data) => fs::write(&path, data),
546            Content::Stream { offset, size } => file
547                .seek(SeekFrom::Start(offset))
548                .and_then(|_| File::create(&path))
549                .and_then(|mut out| {
550                    let copied = io::copy(&mut file.by_ref().take(size), &mut out)?;
551                    if copied == size {
552                        Ok(())
553                    } else {
554                        Err(Error::new(
555                            ErrorKind::UnexpectedEof,
556                            "the entry is truncated",
557                        ))
558                    }
559                }),
560        }
561        .prepend_error(fail("Failed to write"))?;
562        if self.owners.insert(key, (relative, index)).is_none() {
563            self.files += 1;
564        }
565        Ok(())
566    }
567}
568
569/// The content of a `.bin` entry as text when it is a rapified config (`true`), else as it was. A config
570/// that cannot be derapified is kept with a `derapify-failed` warning.
571fn derapify_entry<F: Read + Seek>(
572    entry: &IndexEntry,
573    content: Content,
574    file: &mut F,
575    warnings: &mut dyn WarningSink,
576) -> Result<(bool, Content), Error> {
577    let name = entry.name.as_str();
578    let fail = |what: &str| format!("{what} \"{}\":", printable(name));
579    let head = match &content {
580        Content::Bytes(data) => data.get(..4).map(<[u8]>::to_vec),
581        Content::Stream { offset, size } if *size >= 4 => {
582            Some(read_at(file, *offset, 4).prepend_error(fail("Failed to read"))?)
583        }
584        Content::Stream { .. } => None,
585    };
586    if !head.is_some_and(|h| is_rapified(&h)) {
587        return Ok((false, content));
588    }
589    let data = match content {
590        Content::Bytes(data) => data,
591        Content::Stream { offset, size } if size <= MAX_IN_MEMORY => {
592            read_at(file, offset, size).prepend_error(fail("Failed to read"))?
593        }
594        Content::Stream { offset, size } => {
595            warnings.warn(Warning::new(
596                Some("derapify-failed"),
597                format!(
598                    "Keeping \"{}\" as it is: the entry is too large to derapify.",
599                    printable(name)
600                ),
601            ));
602            return Ok((false, Content::Stream { offset, size }));
603        }
604    };
605    match derapify(&data) {
606        Ok(text) => Ok((true, Content::Bytes(text))),
607        Err(e) => {
608            warnings.warn(Warning::new(
609                Some("derapify-failed"),
610                format!("Keeping \"{}\" as it is: {e}", printable(name)),
611            ));
612            Ok((false, Content::Bytes(data)))
613        }
614    }
615}
616
617/// `size` bytes of `file` at `offset`; the caller has checked `size` against `MAX_IN_MEMORY`.
618fn read_at<F: Read + Seek>(file: &mut F, offset: u64, size: u64) -> Result<Vec<u8>, Error> {
619    file.seek(SeekFrom::Start(offset))?;
620    let mut data = Vec::new();
621    file.by_ref().take(size).read_to_end(&mut data)?;
622    if u64::try_from(data.len()).ok() != Some(size) {
623        return Err(Error::new(
624            ErrorKind::UnexpectedEof,
625            "the entry is truncated",
626        ));
627    }
628    Ok(data)
629}
630
631/// Replaces `target` with the finished `staging` folder. The old tree is renamed away first, so a failure
632/// puts it back.
633fn swap(staging: &mut Staging, target: &Path, warnings: &mut dyn WarningSink) -> Result<(), Error> {
634    let shown = printable(&target.display().to_string());
635    let old = match fs::symlink_metadata(target) {
636        Ok(_) => {
637            let mut old = staging.path.clone().into_os_string();
638            old.push(".old");
639            let old = PathBuf::from(old);
640            fs::rename(target, &old)
641                .prepend_error(format!("Failed to move the old target \"{shown}\" away:"))?;
642            Some(old)
643        }
644        Err(_) => None,
645    };
646    if let Err(e) = fs::rename(&staging.path, target) {
647        if let Some(old) = &old {
648            // put the old tree back; if that fails too the error below names where it is
649            if let Err(back) = fs::rename(old, target) {
650                return Err(error!(
651                    "Failed to move the new tree to \"{shown}\": {e}; the old tree is in \"{}\" ({back}).",
652                    printable(&old.display().to_string())
653                ));
654            }
655        }
656        return Err(e).prepend_error(format!("Failed to move the new tree to \"{shown}\":"));
657    }
658    staging.armed = false;
659    if let Some(old) = old
660        && let Err(e) = fs::remove_dir_all(&old)
661    {
662        warnings.warn(Warning::new(
663            Some("old-tree-left"),
664            format!(
665                "Could not remove the old tree \"{}\": {e}",
666                printable(&old.display().to_string())
667            ),
668        ));
669    }
670    Ok(())
671}
672
673/// Extracts `source` into `target`.
674///
675/// `source` is a DayZ client or server folder, a mod folder or a single PBO. For a folder, every `*.pbo`
676/// directly in its `dta` and `addons` subfolders (any case) is read, in sorted path order. The entries of
677/// each PBO go to `<target>/<prefix>/<entry>`; an empty prefix means the file stem of the PBO. Names are
678/// validated like [`crate::pbo::unpack`] does and unsafe ones are skipped with a warning. When two PBOs
679/// write the same path (ignoring case), the later one wins and a `duplicate-path` warning names both. When
680/// an entry would be a file where an earlier one has a folder, or the reverse, the first stays and the
681/// later one is skipped with an `extract-path-clash` warning.
682/// With `options.derapify`, a rapified `*.bin` becomes a `.cpp` of the same name, or stays a `.bin` with a
683/// `derapify-failed` warning. `options.only` and `options.exclude` select entries like they do for
684/// [`crate::pbo::unpack`].
685///
686/// The tree is written to a staging folder next to `target` and then replaces it with one rename, so a
687/// re-run drops files that no longer exist and a failure leaves the old tree alone. The file `pbo-map.tsv`
688/// in the target has one line per PBO, `prefix<TAB>path of the PBO relative to source` with `/`
689/// separators, sorted by prefix. The prefix is written with `/` instead of `\` (like the tree below the target); then
690/// `\`, TAB, CR and LF in either column are written as `\\`, `\t`, `\r` and `\n`, so every `\` in the file starts
691/// an escape. The bytes of the prefix as stored are in the `--json` output of `inspect`.
692///
693/// # Errors
694///
695/// Returns an error if the source has no PBO or cannot be read, a PBO is malformed or an entry is truncated
696/// (its data ends past the end of the file), an entry cannot be read or decompressed, the target exists and
697/// `options.force` is not set, the target is not a folder, is inside the source or contains it, the target
698/// folder is neither empty nor the result of an earlier extract (no `pbo-map.tsv`), or the tree cannot be
699/// written. A failure leaves an existing target alone.
700pub fn extract(
701    source: &Path,
702    target: &Path,
703    options: &ExtractOptions,
704    warnings: &mut dyn WarningSink,
705) -> Result<ExtractSummary, Error> {
706    let sources = find_pbos(source)?;
707    // before anything looks at the target: `a/missing/..` must fail the same way where it resolves to `a`
708    target_name(target)?;
709    check_target(&sources, source, target, options.force)?;
710    let mut staging = create_staging(target)?;
711    let mut run = Run {
712        staging: &staging.path.clone(),
713        options,
714        names: sources.iter().map(|s| s.relative.clone()).collect(),
715        filter: EntryFilter::new(options.only.clone(), options.exclude.clone()),
716        owners: BTreeMap::new(),
717        map: Vec::new(),
718        files: 0,
719    };
720    for (index, source) in sources.iter().enumerate() {
721        run.pbo(index, source, warnings)?;
722    }
723    run.map.sort();
724    let mut text = Vec::new();
725    for (prefix, path) in &run.map {
726        escape(prefix, &mut text);
727        text.push(b'\t');
728        escape(path.as_bytes(), &mut text);
729        text.push(b'\n');
730    }
731    fs::write(staging.path.join(MAP_FILE), &text).prepend_error("Failed to write the PBO map:")?;
732    let summary = ExtractSummary {
733        pbos: sources.len(),
734        files: run.files,
735    };
736    swap(&mut staging, target, warnings)?;
737    Ok(summary)
738}