ltk_wad 0.5.0

//! Turning a resolved path into a name a file system will take.
//!
//! Three things stand between a path a resolver gave and a file on disk: the
//! path may be one the extraction must refuse outright ([`is_evil`]), another
//! path of the same extraction may need it to be a directory
//! ([`DirectoryPaths`]), or the file system may refuse the name when the write
//! is tried ([`is_path_conflict`]). The first two are settled before anything
//! is written, which is what makes one archive and one hash table give one
//! output tree on every run.
//!
//! `docs/design/wad-extractor.md` records why, and what was measured.

use std::{borrow::Cow, collections::HashSet, io};

use camino::{Utf8Path, Utf8PathBuf};
use ltk_file::LeagueFileKind;

use crate::WadChunk;

use super::resolver::hex_name;

/// Whether `path` is one an extraction must refuse to write.
///
/// A resolver's paths are untrusted, a hash table and name recovery alike;
/// the extractor module docs say why, under "Paths the extraction will not
/// write". A path is evil when joining it onto the output directory would not
/// give a plain file plainly under that directory:
///
/// - it starts at a root, a drive or a network share, so the join ignores the
///   output directory;
/// - a component is `..`, which reaches the directory above;
/// - a component holds a `:`, naming a Windows drive or an alternate data
///   stream instead of a file the directory lists;
/// - a component ends in a dot or a space, which Windows strips before it
///   looks the name up, so `notes.txt.` and `notes.txt` are one file under two
///   names and would walk past the check for two chunks claiming one path;
/// - or it names no file at all, holding nothing but separators and `.`.
///
/// The last two rules are Windows behaviour, applied wherever the extraction
/// runs. That is deliberate: one archive and one hash table then give one
/// output tree on every host, and a test on any of them catches a table that
/// would misbehave on Windows. It costs two conditions.
///
/// `path` is read as the raw string a resolver gave. Turning it into a
/// [`Utf8Path`] first would normalise away the very things this looks for, and
/// `/` and `\` both separate components whatever the host, so a table written
/// on Windows cannot escape on Linux or the other way round.
///
/// The check is lexical. It says the joined path cannot name a file outside the
/// output directory; it says nothing about a symlink an output tree already
/// holds.
pub(super) fn is_evil(path: &str) -> bool {
    if path.starts_with(['/', '\\']) {
        return true;
    }

    let mut names_a_file = false;
    for component in path.split(['/', '\\']) {
        /* `a//b` and a trailing separator each give an empty component, and `.`
        is the directory the walk already stands in. `join` steps over both. */
        match component {
            "" | "." => continue,
            ".." => return true,
            _ => {}
        }
        if component.contains(':') || component.ends_with(['.', ' ']) {
            return true;
        }
        names_a_file = true;
    }

    !names_a_file
}

/// The directories a set of paths names, each a path in its own right.
///
/// A WAD is a flat map from path to bytes, so it can hold both `x` and `x/y`.
/// A file system holds one or the other, so one of the two has to move. Which
/// one is settled against this, built over the paths an extraction resolved
/// before it writes any of them. Settling it at the write instead would follow
/// whichever worker reached the file system first, and two runs of one archive
/// could give two trees.
#[derive(Debug, Default)]
pub(super) struct DirectoryPaths(HashSet<String>);

impl DirectoryPaths {
    /// The directories `paths` names.
    pub(super) fn of(paths: impl IntoIterator<Item = impl AsRef<str>>) -> Self {
        let mut directories = HashSet::new();
        for path in paths {
            let path = plain_path(path.as_ref());
            for (end, _) in path.match_indices('/') {
                let directory = &path[..end];
                /* The paths of one tree share their directories, so most of
                these are there already and cost nothing. */
                if !directories.contains(directory) {
                    directories.insert(directory.to_owned());
                }
            }
        }
        Self(directories)
    }

    /// Whether a path of the same set needs `path` to be a directory.
    pub(super) fn holds(&self, path: &str) -> bool {
        self.0.contains(plain_path(path).as_ref())
    }
}

/// `path` with one `/` between its components and nothing else.
///
/// The components are the ones a join steps onto, so an empty one from `a//b`
/// or from a trailing separator is dropped, as is a `.`, and `\` separates as
/// `/` does whatever the host. Borrowed when `path` is in that form already,
/// which nearly every path a hash table holds is.
pub(super) fn plain_path(path: &str) -> Cow<'_, str> {
    if !path.contains('\\') && !path.split('/').any(|part| matches!(part, "" | ".")) {
        return Cow::Borrowed(path);
    }
    Cow::Owned(
        path.split(['/', '\\'])
            .filter(|part| !matches!(*part, "" | "."))
            .collect::<Vec<_>>()
            .join("/"),
    )
}

/// Whether `error` says something already occupies `path`, rather than the
/// write having failed for a reason a different name would not mend.
///
/// Windows reports a directory standing in the way as `PermissionDenied`, and
/// reports a file it cannot open the same way, so `path.is_dir()` breaks the
/// tie between the two.
pub(super) fn is_path_conflict(error: &io::Error, path: &Utf8Path) -> bool {
    use io::ErrorKind as Kind;

    match error.kind() {
        Kind::InvalidFilename | Kind::IsADirectory | Kind::AlreadyExists | Kind::NotADirectory => {
            true
        }
        Kind::PermissionDenied => path.is_dir(),
        _ => false,
    }
}

/// `<hash>.<ext>`, the name a chunk takes when the file system refuses its own.
pub(super) fn hashed_name(chunk: &WadChunk, chunk_kind: LeagueFileKind) -> Utf8PathBuf {
    let mut hashed_path = Utf8PathBuf::from(hex_name(chunk.path_hash));
    if let Some(ext) = chunk_kind.extension() {
        hashed_path.set_extension(ext);
    }
    hashed_path
}

/// `<name>.ltk`, the name a chunk takes when a directory holds its own.
///
/// The suffix is added and never substituted, so stripping a trailing `.ltk`
/// gives back the path the chunk was named for, whatever that path held. A
/// caller that hashes an extracted file's path back to its chunk needs exactly
/// that, and a name built from the file's stem could not give it: `foo.bin`
/// renamed to `foo.ltk.dds` says nothing about the `.bin` it came from.
pub(super) fn ltk_name(file_name: &str) -> String {
    format!("{file_name}.ltk")
}

/// `path` with the suffix on the end of its file name.
///
/// The suffix goes on the end of the path, which is the same thing: a path's
/// file name is its tail. Going through
/// [`set_file_name`](Utf8PathBuf::set_file_name) would not be, because that
/// re-joins the path with the host's separator and would hand back
/// `assets\thing.ltk` on Windows where every un-renamed chunk reports
/// `assets/thing`. A caller stripping the suffix off that would hash a path
/// the archive was never built from.
pub(super) fn ltk_path(path: &Utf8Path) -> Utf8PathBuf {
    Utf8PathBuf::from(ltk_name(path.as_str()))
}