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 std::os::unix::io::{AsFd, BorrowedFd, OwnedFd};

/// Like [`std::borrow::Cow`] but without the [`ToOwned`] requirement, and only
/// for file descriptors.
///
/// This is mainly useful when you need to write a function that takes something
/// equivalent to `Option<BorrowedFd<'_>>` and opens an alternative [`OwnedFd`]
/// (or any other `Fd: AsFd`) if passed [`None`]. Normally you cannot really do
/// this smoothly.
///
/// Note that due to Rust's temporaries handling and restrictions of the
/// [`AsFd`] trait, you need to do something like the following:
///
/// ```ignore
/// fn procfs_foobar(fd: Option<BorrowedFd<'_>>) -> Result<(), Error> {
///     let fd = match fd {
///         None => MaybeOwnedFd::OwnedFd(File::open("/proc")?),
///         Some(fd) => MaybeOwnedFd::BorrowedFd(fd),
///     };
///     let fd = fd.as_fd(); // BorrowedFd<'_>
///     // do something with fd
/// }
/// ```
///
/// This will give you a [`BorrowedFd`] with minimal fuss.
///
/// [`OwnedFd`]: std::os::unix::io::OwnedFd
/// [`ToOwned`]: std::borrow::ToOwned
#[derive(Debug)]
pub(crate) enum MaybeOwnedFd<'fd, Fd>
where
    Fd: AsFd,
{
    OwnedFd(Fd),
    BorrowedFd(BorrowedFd<'fd>),
}

impl<'fd> From<OwnedFd> for MaybeOwnedFd<'fd, OwnedFd> {
    fn from(fd: OwnedFd) -> Self {
        Self::OwnedFd(fd)
    }
}

impl<'fd, Fd> From<BorrowedFd<'fd>> for MaybeOwnedFd<'fd, Fd>
where
    Fd: AsFd,
{
    fn from(fd: BorrowedFd<'fd>) -> Self {
        Self::BorrowedFd(fd)
    }
}

// I wish we could make this "impl AsFd for MaybeOwnedFd" but the lifetimes
// don't match, even though it really feels like it should be possible.
impl<'fd, Fd> MaybeOwnedFd<'fd, Fd>
where
    Fd: AsFd,
{
    /// Unwrap `MaybeOwnedFd` into the `OwnedFd` variant if possible.
    ///
    /// Returns `Err(self)` if this is a shared reference.
    pub(crate) fn try_into_owned(self) -> Result<Fd, Self> {
        match self {
            Self::OwnedFd(fd) => Ok(fd),
            Self::BorrowedFd(_) => Err(self),
        }
    }

    /// Unwrap `MaybeOwnedFd` into the `OwnedFd` variant if possible.
    pub(crate) fn into_owned(self) -> Option<Fd> {
        self.try_into_owned().ok()
    }

    /// Very similar in concept to [`AsFd::as_fd`] but with some additional
    /// lifetime restrictions that make it incompatible with [`AsFd`].
    pub(crate) fn as_fd<'a>(&'a self) -> BorrowedFd<'a>
    where
        'a: 'fd,
    {
        match self {
            Self::OwnedFd(fd) => fd.as_fd(),
            Self::BorrowedFd(fd) => fd.as_fd(),
        }
    }
}

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

    use std::{
        fs::File,
        os::unix::io::{AsFd, AsRawFd, OwnedFd},
    };

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

    #[test]
    fn as_fd() -> Result<(), Error> {
        let f: OwnedFd = File::open(".")?.into();
        let fd = f.as_raw_fd();
        let owned: MaybeOwnedFd<OwnedFd> = f.into();
        assert_matches!(owned, MaybeOwnedFd::OwnedFd(_));
        assert_eq!(owned.as_fd().as_raw_fd(), fd);
        assert_matches!(owned.into_owned(), Some(_));

        let f = File::open(".")?;
        let borrowed: MaybeOwnedFd<OwnedFd> = f.as_fd().into();
        assert_matches!(borrowed, MaybeOwnedFd::BorrowedFd(_));
        assert_matches!(borrowed.into_owned(), None);

        Ok(())
    }

    #[test]
    fn into_owned() -> Result<(), Error> {
        let f: OwnedFd = File::open(".")?.into();
        let owned: MaybeOwnedFd<OwnedFd> = f.into();
        assert_matches!(
            owned,
            MaybeOwnedFd::OwnedFd(_),
            "MaybeOwnedFd::from(OwnedFd)"
        );
        assert_matches!(
            owned.into_owned(),
            Some(_),
            "MaybeOwnedFd::from(OwnedFd).into_owned()"
        );

        let f = File::open(".")?;
        let borrowed: MaybeOwnedFd<OwnedFd> = f.as_fd().into();
        assert_matches!(
            borrowed,
            MaybeOwnedFd::BorrowedFd(_),
            "MaybeOwnedFd::from(BorrowedFd)"
        );
        assert_matches!(
            borrowed.into_owned(),
            None,
            "MaybeOwnedFd::from(BorrowedFd).into_owned()"
        );

        Ok(())
    }

    #[test]
    fn try_into_owned() -> Result<(), Error> {
        let f: OwnedFd = File::open(".")?.into();
        let owned: MaybeOwnedFd<OwnedFd> = f.into();
        assert_matches!(
            owned,
            MaybeOwnedFd::OwnedFd(_),
            "MaybeOwnedFd::from(OwnedFd)"
        );
        assert_matches!(
            owned.try_into_owned(),
            Ok(_),
            "MaybeOwnedFd::from(OwnedFd).try_into_owned()"
        );

        let f = File::open(".")?;
        let borrowed: MaybeOwnedFd<OwnedFd> = f.as_fd().into();
        assert_matches!(
            borrowed,
            MaybeOwnedFd::BorrowedFd(_),
            "MaybeOwnedFd::from(BorrowedFd)"
        );
        assert_matches!(
            borrowed.try_into_owned(),
            Err(_),
            "MaybeOwnedFd::from(BorrowedFd).try_into_owned()"
        );

        Ok(())
    }
}