pathrs 0.2.4

// SPDX-License-Identifier: MPL-2.0 OR LGPL-3.0-or-later
/*
 * libpathrs: safe path resolution on Linux
 * Copyright (C) 2019-2025 SUSE LLC
 * Copyright (C) 2026 Aleksa Sarai <cyphar@cyphar.com>
 *
 * == MPL-2.0 ==
 *
 *  This Source Code Form is subject to the terms of the Mozilla Public
 *  License, v. 2.0. If a copy of the MPL was not distributed with this
 *  file, You can obtain one at https://mozilla.org/MPL/2.0/.
 *
 * Alternatively, this Source Code Form may also (at your option) be used
 * under the terms of the GNU Lesser General Public License Version 3, as
 * described below:
 *
 * == LGPL-3.0-or-later ==
 *
 *  This program is free software: you can redistribute it and/or modify it
 *  under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or (at
 *  your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 * Public License  for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with this program. If not, see <https://www.gnu.org/licenses/>.
 */

use crate::error::{Error, ErrorImpl};

use std::{
    collections::VecDeque,
    ffi::{CString, OsStr, OsString},
    os::unix::ffi::OsStrExt,
    path::Path,
};

pub(crate) trait ToCString {
    /// Convert to a CStr.
    fn to_c_string(&self) -> CString;
}

impl ToCString for OsStr {
    fn to_c_string(&self) -> CString {
        let filtered: Vec<_> = self
            .as_bytes()
            .iter()
            .copied()
            .take_while(|&c| c != b'\0')
            .collect();
        CString::new(filtered).expect("nul bytes should've been excluded")
    }
}

impl ToCString for Path {
    fn to_c_string(&self) -> CString {
        self.as_os_str().to_c_string()
    }
}

/// Helper to strip trailing / components from a path.
pub(crate) fn path_strip_trailing_slash(path: &Path) -> (&Path, bool) {
    let path_bytes = path.as_os_str().as_bytes();
    let idx = match path_bytes.iter().rposition(|c| *c != b'/') {
        Some(idx) => idx,
        None => {
            if path_bytes.len() > 1 {
                // Nothing but b'/' components -- return a single /.
                return (Path::new("/"), true);
            } else {
                // Either "/" or "".
                return (path, false);
            }
        }
    };
    if idx == path_bytes.len() - 1 {
        // No slashes to strip.
        (path, false)
    } else {
        // Strip trailing slashes.
        (Path::new(OsStr::from_bytes(&path_bytes[..=idx])), true)
    }
}

/// Helper to split a Path into its parent directory and trailing path. The
/// trailing component is guaranteed to not contain a directory separator.
pub(crate) fn path_split(path: &'_ Path) -> Result<(&'_ Path, Option<&'_ Path>), Error> {
    let (dir, base) = path
        .partial_ancestors()
        .next()
        .expect("partial_ancestors iterator must return at least one entry");

    // It's critical we are only touching the final component in the path.
    // If there are any other path components we must bail.
    if let Some(base) = base {
        let base_bytes = base.as_os_str().as_bytes();
        if base_bytes == b"" {
            Err(ErrorImpl::SafetyViolation {
                description: "trailing component of split pathname is empty".into(),
            })?
        }
        if base_bytes.contains(&b'/') {
            Err(ErrorImpl::SafetyViolation {
                description: "trailing component of split pathname contains '/'".into(),
            })?
        }
    }

    Ok((dir, base))
}

/// RawComponents is like [`Components`] except that no normalisation is done
/// for any path components ([`Components`] normalises "/./" components), and
/// all of the components are simply [`OsStr`].
///
/// [`Components`]: std::path::Components
#[derive(Debug)]
pub(crate) struct RawComponents<'a> {
    inner: Option<&'a OsStr>,
}

impl<'a> Iterator for RawComponents<'a> {
    type Item = &'a OsStr;

    fn next(&mut self) -> Option<Self::Item> {
        match self.inner {
            None => None,
            Some(inner) => {
                let (next, remaining) = match memchr::memchr(b'/', inner.as_bytes()) {
                    None => (inner, None),
                    Some(idx) => {
                        let (head, mut tail) = inner.as_bytes().split_at(idx);
                        tail = &tail[1..]; // strip slash
                        (OsStrExt::from_bytes(head), Some(OsStrExt::from_bytes(tail)))
                    }
                };
                self.inner = remaining;
                assert!(
                    !next.as_bytes().contains(&b'/'),
                    "individual path component {next:?} contains '/'",
                );
                Some(next)
            }
        }
    }
}

impl DoubleEndedIterator for RawComponents<'_> {
    fn next_back(&mut self) -> Option<Self::Item> {
        match self.inner {
            None => None,
            Some(inner) => {
                let (next, remaining) = match memchr::memrchr(b'/', inner.as_bytes()) {
                    None => (inner, None),
                    Some(idx) => {
                        let (head, mut tail) = inner.as_bytes().split_at(idx);
                        tail = &tail[1..]; // strip slash
                        (OsStrExt::from_bytes(tail), Some(OsStrExt::from_bytes(head)))
                    }
                };
                self.inner = remaining;
                assert!(
                    !next.as_bytes().contains(&b'/'),
                    "individual path component {next:?} contains '/'",
                );
                Some(next)
            }
        }
    }
}

impl RawComponents<'_> {
    pub(crate) fn prepend(&mut self, deque: &mut VecDeque<OsString>) {
        self.map(|p| p.to_os_string())
            // VecDeque doesn't have an amortized way of prepending a
            // Vec, so we need to do this manually. We need to rev() the
            // iterator since we're pushing to the front each time.
            .rev()
            .for_each(|p| deque.push_front(p));
    }
}

#[derive(Debug)]
enum AncestorsIterState {
    Start,
    Middle(usize),
    End,
}

#[derive(Debug)]
pub(crate) struct Ancestors<'p> {
    state: AncestorsIterState,
    inner: &'p Path,
}

impl<'p> Iterator for Ancestors<'p> {
    // (ancestor, remaining_path)
    type Item = (&'p Path, Option<&'p Path>);

    fn next(&mut self) -> Option<Self::Item> {
        let inner_bytes = self.inner.as_os_str().as_bytes();
        // Search for "/" in the remaining path.
        let found_idx = match self.state {
            AncestorsIterState::End => return None,
            AncestorsIterState::Start => memchr::memrchr(b'/', inner_bytes),
            AncestorsIterState::Middle(idx) => memchr::memrchr(b'/', &inner_bytes[..idx]),
        };
        let next_idx = match found_idx {
            None => {
                self.state = AncestorsIterState::End;
                return Some((
                    Path::new("."),
                    if inner_bytes.is_empty() {
                        None
                    } else {
                        Some(self.inner)
                    },
                ));
            }
            Some(idx) => idx,
        };

        // TODO: Skip over multiple "//" components.

        // Split the path.
        // TODO: We probably want to move some of the None handling here to
        // split_path()...
        let (ancestor_bytes, remaining_bytes) = match inner_bytes.split_at(next_idx) {
            (b"", b"/") => (&b"/"[..], None),
            (dir, b"/") => (dir, None),
            (b"", base) => (&b"/"[..], Some(&base[1..])),
            (dir, base) => (dir, Some(&base[1..])),
        };

        // Update the state.
        self.state = match ancestor_bytes {
            b"" | b"." | b"/" => AncestorsIterState::End,
            _ => AncestorsIterState::Middle(next_idx),
        };

        // Not quite sure why we need to annotate ::<OsStr> since
        // OsStrExt::from_bytes() returns a plain OsStr. Oh well.
        Some((
            Path::new::<OsStr>(OsStrExt::from_bytes(ancestor_bytes)),
            remaining_bytes
                .map(OsStrExt::from_bytes)
                .map(Path::new::<OsStr>),
        ))
    }
}

pub(crate) trait PathIterExt {
    fn raw_components(&self) -> RawComponents<'_>;
    fn partial_ancestors(&self) -> Ancestors<'_>;
}

impl PathIterExt for Path {
    fn raw_components(&self) -> RawComponents<'_> {
        RawComponents {
            inner: Some(self.as_os_str()),
        }
    }

    fn partial_ancestors(&self) -> Ancestors<'_> {
        Ancestors {
            state: AncestorsIterState::Start,
            inner: self,
        }
    }
}

impl<P: AsRef<Path>> PathIterExt for P {
    fn raw_components(&self) -> RawComponents<'_> {
        self.as_ref().raw_components()
    }

    fn partial_ancestors(&self) -> Ancestors<'_> {
        self.as_ref().partial_ancestors()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    use std::path::{Path, PathBuf};

    use anyhow::{Context, Error};
    use pretty_assertions::assert_eq;

    // TODO: Add propcheck tests?

    macro_rules! path_strip_slash_tests {
        // path_strip_slash_tests! {
        //      abc("a/b" => "a/b");
        //      xyz("/foo/bar///" => "/foo/bar");
        //      xyz("//" => "/");
        // }
        ($($test_name:ident ($path:expr => $stripped:expr, $trailing:expr));* $(;)? ) => {
            paste::paste! {
                $(
                    #[test]
                    fn [<path_strip_slash_ $test_name>]() {
                        let path: PathBuf = $path.into();
                        let (got_path, got_trailing) = path_strip_trailing_slash(&path);

                        let want_path: PathBuf = $stripped.into();
                        let want_trailing = $trailing;

                        assert_eq!(
                            got_path.as_os_str(), want_path.as_os_str(),
                            "stripping {path:?} produced wrong result -- got {got_path:?}",
                        );
                        assert_eq!(
                            got_trailing, want_trailing,
                            "expected {path:?} to have trailing_slash={want_trailing}",
                        );
                    }
                )*
            }
        };
    }

    path_strip_slash_tests! {
        empty("" => "", false);
        dot("." => ".", false);
        root("/" => "/", false);

        regular_notrailing1("/foo/bar/baz" => "/foo/bar/baz", false);
        regular_notrailing2("../../a/b/c" => "../../a/b/c", false);
        regular_notrailing3("/a" => "/a", false);

        regular_trailing1("/foo/bar/baz/" => "/foo/bar/baz", true);
        regular_trailing2("../../a/b/c/" => "../../a/b/c", true);
        regular_trailing3("/a/" => "/a", true);

        trailing_dot1("/foo/." => "/foo/.", false);
        trailing_dot2("foo/../bar/../." => "foo/../bar/../.", false);

        root_multi1("////////" => "/", true);
        root_multi2("//" => "/", true);

        complex1("foo//././bar/baz//./" => "foo//././bar/baz//.", true);
        complex2("//a/.///b/../../" => "//a/.///b/../..", true);
        complex3("../foo/bar/.///" => "../foo/bar/.", true);
    }

    macro_rules! path_split_tests {
        // path_tests! {
        //      abc("a/b" => "a", Some("b"));
        //      xyz("/foo/bar/baz" => "/foo/bar", Some("baz"));
        //      xyz("/" => "/", None);
        // }
        ($($test_name:ident ($path:expr => $dir:expr, $file:expr));* $(;)? ) => {
            paste::paste! {
                $(
                    #[test]
                    fn [<path_split_ $test_name>]() -> Result<(), Error> {
                        let path: PathBuf = $path.into();
                        let (got_dir, got_file) = path_split(&path)
                            .with_context(|| format!("path_split({path:?})"))?;

                        let want_dir: PathBuf = $dir.into();
                        let want_file = {
                            let file: Option<&str> = $file;
                            file.map(PathBuf::from)
                        };

                        assert_eq!(
                            (got_dir.as_os_str(), got_file.map(Path::as_os_str)),
                            (want_dir.as_os_str(), want_file.as_ref().map(|p| p.as_os_str()))
                        );
                        Ok(())
                    }
                )*
            }
        };
    }

    path_split_tests! {
        empty("" => ".", None);
        root("/" => "/", None);

        single1("single" => ".", Some("single"));
        single2("./single" => ".", Some("single"));
        single_root1("/single" => "/", Some("single"));

        multi1("foo/bar" => "foo", Some("bar"));
        multi2("foo/bar/baz" => "foo/bar", Some("baz"));
        multi3("./foo/bar/baz" => "./foo/bar", Some("baz"));
        multi_root1("/foo/bar" => "/foo", Some("bar"));
        multi_root2("/foo/bar/baz" => "/foo/bar", Some("baz"));

        trailing_dot1("/foo/." => "/foo", Some("."));
        trailing_dot2("foo/../bar/../." => "foo/../bar/..", Some("."));

        trailing_slash1("/foo/" => "/foo", None);
        trailing_slash2("foo/bar///" => "foo/bar//", None);
        trailing_slash3("./" => ".", None);
        trailing_slash4("//" => "/", None);

        complex1("foo//././bar/baz//./xyz" => "foo//././bar/baz//.", Some("xyz"));
        complex2("//a/.///b/../../xyz" => "//a/.///b/../..", Some("xyz"));
        complex3("../foo/bar/.///baz" => "../foo/bar/.//", Some("baz"));
    }

    macro_rules! path_ancestor_tests {
        ($($test_name:ident ($path:expr => { $(($ancestor:expr, $remaining:expr)),* }));* $(;)? ) => {
            paste::paste! {
                $(
                    #[test]
                    fn [<path_partial_ancestors_ $test_name>]() {
                        let path = PathBuf::from($path);
                        let expected: Vec<(&Path, Option<&Path>)> = vec![
                            $({
                                let ancestor: &str = $ancestor;
                                let remaining: Option<&str> = $remaining;
                                (Path::new(ancestor), remaining.map(Path::new))
                            }),*
                        ];

                        let got = path.partial_ancestors().collect::<Vec<_>>();
                        assert_eq!(got, expected, "unexpected results from partial_ancestors");
                    }
                )*
            }
        }
    }

    path_ancestor_tests! {
        empty("" => { (".", None) });
        root("/" => { ("/", None) });

        single1("single" => { (".", Some("single")) });
        single2("./single" => { (".", Some("single")) });
        single_root1("/single" => { ("/", Some("single")) });

        multi1("foo/bar" => {
            ("foo", Some("bar")),
            (".", Some("foo/bar"))
        });
        multi2("foo/bar/baz" => {
            ("foo/bar", Some("baz")),
            ("foo", Some("bar/baz")),
            (".", Some("foo/bar/baz"))
        });
        multi3("./foo/bar/baz" => {
            ("./foo/bar", Some("baz")),
            ("./foo", Some("bar/baz")),
            (".", Some("foo/bar/baz"))
        });
        multi_root1("/foo/bar" => {
            ("/foo", Some("bar")),
            ("/", Some("foo/bar"))
        });
        multi_root2("/foo/bar/baz" => {
            ("/foo/bar", Some("baz")),
            ("/foo", Some("bar/baz")),
            ("/", Some("foo/bar/baz"))
        });

        trailing_dot1("/foo/." => {
            ("/foo/", Some(".")),
            ("/", Some("foo/."))
        });
        trailing_dot2("foo/../bar/../." => {
            ("foo/../bar/..", Some(".")),
            ("foo/../bar", Some("../.")),
            ("foo/..", Some("bar/../.")),
            ("foo", Some("../bar/../.")),
            (".", Some("foo/../bar/../."))
        });


        trailing_slash1("/foo/" => {
            ("/foo", None),
            ("/", Some("foo"))
        });
        // TODO: This should probably be fixed so we skip over "//" components.
        trailing_slash2("foo/bar///" => {
            ("foo/bar//", None),
            ("foo/bar/", Some("/")),
            ("foo/bar", Some("//")),
            ("foo", Some("bar///")),
            (".", Some("foo/bar///"))
        });
        trailing_slash3("./" => {
            (".", None)
        });
        trailing_slash4("//" => {
            ("/", None)
        });

        // TODO: This should probably be fixed so we skip over "//" components.
        complex1("foo//././bar/baz//./xyz" => {
            ("foo//././bar/baz//.", Some("xyz")),
            ("foo//././bar/baz/", Some("./xyz")),
            ("foo//././bar/baz", Some("/./xyz")),
            ("foo//././bar", Some("baz//./xyz")),
            ("foo//./.", Some("bar/baz//./xyz")),
            ("foo//.", Some("./bar/baz//./xyz")),
            ("foo/", Some("././bar/baz//./xyz")),
            ("foo", Some("/././bar/baz//./xyz")),
            (".", Some("foo//././bar/baz//./xyz"))
        });
        complex2("//a/.///b/../../xyz" => {
            ("//a/.///b/../..", Some("xyz")),
            ("//a/.///b/..", Some("../xyz")),
            ("//a/.///b", Some("../../xyz")),
            ("//a/.//", Some("b/../../xyz")),
            ("//a/./", Some("/b/../../xyz")),
            ("//a/.", Some("//b/../../xyz")),
            ("//a", Some(".///b/../../xyz")),
            //("//", Some("a/.///b/../../xyz")),
            ("/", Some("a/.///b/../../xyz"))
        });
        complex3("../foo/bar/.///baz" => {
            ("../foo/bar/.//", Some("baz")),
            ("../foo/bar/./", Some("/baz")),
            ("../foo/bar/.", Some("//baz")),
            ("../foo/bar", Some(".///baz")),
            ("../foo", Some("bar/.///baz")),
            ("..", Some("foo/bar/.///baz")),
            (".", Some("../foo/bar/.///baz"))
        });
    }
}