uv_fs/

lib.rs

use std::io;
use std::path::{Path, PathBuf};
use std::time::SystemTime;

#[cfg(unix)]
use std::os::unix::fs::MetadataExt;
#[cfg(windows)]
use std::os::windows::io::AsRawHandle;

#[cfg(target_os = "linux")]
use std::time::{Duration, UNIX_EPOCH};

#[cfg(feature = "tokio")]
use std::io::Read;

#[cfg(feature = "tokio")]
use encoding_rs_io::DecodeReaderBytes;
#[cfg(target_os = "linux")]
use rustix::fs::{AtFlags, CWD as RUSTIX_CWD, StatxFlags, statx};
use tempfile::NamedTempFile;
use tracing::{debug, warn};
#[cfg(windows)]
use windows::Win32::Foundation::HANDLE;
#[cfg(windows)]
use windows::Win32::Storage::FileSystem::{BY_HANDLE_FILE_INFORMATION, GetFileInformationByHandle};

pub use crate::locked_file::*;
pub use crate::path::*;
pub use crate::read::ValidatedReader;
pub use crate::space::{PhysicalSpaceError, physical_space, supports_fine_grained_accounting};

pub mod cachedir;
#[cfg(target_os = "macos")]
mod hardlink_macos;
pub mod link;
mod locked_file;
mod path;
mod read;
mod space;
pub mod which;

/// Return the number of hardlinks to a file.
#[cfg(unix)]
pub fn hardlink_count(path: &Path) -> io::Result<u64> {
    Ok(fs_err::metadata(path)?.nlink())
}

/// Return the number of hardlinks to a file.
#[cfg(windows)]
#[expect(unsafe_code)]
pub fn hardlink_count(path: &Path) -> io::Result<u64> {
    let file = fs_err::File::open(path)?;
    let mut information = BY_HANDLE_FILE_INFORMATION::default();
    // SAFETY: The file handle remains open for the duration of the call, and `information`
    // points to a valid, writable structure of the type expected by the Windows API.
    unsafe { GetFileInformationByHandle(HANDLE(file.as_raw_handle()), &raw mut information) }?;
    Ok(u64::from(information.nNumberOfLinks))
}

/// Return an error on platforms that cannot report hardlink counts.
#[cfg(not(any(unix, windows)))]
pub fn hardlink_count(_path: &Path) -> io::Result<u64> {
    Err(io::Error::new(
        io::ErrorKind::Unsupported,
        "hardlink counts are not supported on this platform",
    ))
}

/// Collect regular files whose only hardlink is their entry in this directory.
///
/// Ignores symlink entries and uses bulk metadata reads on macOS. Returns `None` when the fast path
/// is unavailable, required attributes are missing, or subdirectories need a recursive walk.
/// No candidates are returned unless the entire directory can use the fast path.
///
/// Callers deleting these files must prevent concurrent changes to the directory and hardlink
/// counts throughout both the scan and deletion.
pub fn files_with_one_hardlink(path: &Path) -> io::Result<Option<Vec<PathBuf>>> {
    #[cfg(target_os = "macos")]
    {
        hardlink_macos::files_with_one_hardlink(path)
    }
    #[cfg(not(target_os = "macos"))]
    {
        let _ = path;
        Ok(None)
    }
}

/// Return a path's creation time, including on Linux targets where [`std::fs::Metadata::created`]
/// does not expose the filesystem birth time.
pub fn created_time(path: &Path, metadata: &std::fs::Metadata) -> io::Result<SystemTime> {
    #[cfg(target_os = "linux")]
    {
        let _ = metadata;

        let metadata = statx(
            RUSTIX_CWD,
            path,
            AtFlags::empty(),
            StatxFlags::BASIC_STATS | StatxFlags::BTIME,
        )?;

        if metadata.stx_mask & StatxFlags::BTIME.bits() == 0 {
            return Err(io::Error::new(
                io::ErrorKind::Unsupported,
                "creation time is not available for the filesystem",
            ));
        }

        let birth_time = metadata.stx_btime;
        let seconds = Duration::from_secs(birth_time.tv_sec.unsigned_abs());
        let created = if birth_time.tv_sec < 0 {
            UNIX_EPOCH.checked_sub(seconds)
        } else {
            UNIX_EPOCH.checked_add(seconds)
        };

        created
            .filter(|_| birth_time.tv_nsec < 1_000_000_000)
            .and_then(|created| {
                created.checked_add(Duration::from_nanos(u64::from(birth_time.tv_nsec)))
            })
            .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "invalid creation time"))
    }

    #[cfg(not(target_os = "linux"))]
    {
        let _ = path;
        metadata.created()
    }
}

/// Attempt to check if the two paths refer to the same file.
///
/// Returns `Some(true)` if the files are missing, but would be the same if they existed.
pub fn is_same_file_allow_missing(left: &Path, right: &Path) -> Option<bool> {
    // First, check an exact path comparison.
    if left == right {
        return Some(true);
    }

    // Second, check the files directly.
    if let Ok(value) = same_file::is_same_file(left, right) {
        return Some(value);
    }

    // Often, one of the directories won't exist yet so perform the comparison up a level.
    if let (Some(left_parent), Some(right_parent), Some(left_name), Some(right_name)) = (
        left.parent(),
        right.parent(),
        left.file_name(),
        right.file_name(),
    ) {
        match same_file::is_same_file(left_parent, right_parent) {
            Ok(true) => return Some(left_name == right_name),
            Ok(false) => return Some(false),
            _ => (),
        }
    }

    // We couldn't determine if they're the same.
    None
}

/// Reads data from the path and requires that it be valid UTF-8 or UTF-16.
///
/// This uses BOM sniffing to determine if the data should be transcoded from UTF-16 to Rust's
/// `String` type (which uses UTF-8).
///
/// This should generally only be used when one specifically wants to support reading UTF-16
/// transparently.
///
/// If the file path is `-`, then contents are read from stdin instead.
#[cfg(feature = "tokio")]
pub async fn read_to_string_transcode(path: impl AsRef<Path>) -> std::io::Result<String> {
    let path = path.as_ref();
    let raw = if path == Path::new("-") {
        let mut buf = Vec::with_capacity(1024);
        std::io::stdin().read_to_end(&mut buf)?;
        buf
    } else {
        fs_err::tokio::read(path).await?
    };
    let mut buf = String::with_capacity(1024);
    DecodeReaderBytes::new(&*raw)
        .read_to_string(&mut buf)
        .map_err(|err| {
            let path = path.display();
            std::io::Error::other(format!("failed to decode file {path}: {err}"))
        })?;
    Ok(buf)
}

/// Create a junction at `path` pointing to `target`.
///
/// Junctions can be silently broken when involving network paths or non-NTFS filesystems.
///
/// If creation fails but leaves behind an empty directory, it is cleaned up and the original
/// creation error is propagated.
#[cfg(windows)]
fn create_junction(target: &Path, path: &Path) -> std::io::Result<()> {
    use windows::Win32::Foundation::{
        ERROR_ALREADY_EXISTS, ERROR_INVALID_NAME, ERROR_INVALID_PARAMETER,
        ERROR_INVALID_REPARSE_DATA, ERROR_NOT_A_REPARSE_POINT, WIN32_ERROR,
    };

    let create_result = junction::create(target, path);

    match path.metadata() {
        Ok(_) if create_result.is_ok() => Ok(()),
        Ok(_) => {
            // Creation failed but left behind an empty directory. Only clean
            // it up if the directory wasn't already there before we tried.
            if let Err(ref create_err) = create_result {
                if !matches!(
                    create_err
                        .raw_os_error()
                        .map(|err| WIN32_ERROR(err.cast_unsigned())),
                    Some(ERROR_ALREADY_EXISTS)
                ) {
                    // Not a junction (metadata succeeded normally), just
                    // an empty directory left behind by junction::create.
                    let _ = fs_err::remove_dir(path);
                }
            }
            create_result
        }
        Err(err)
            if matches!(
                err.raw_os_error()
                    .map(|err| WIN32_ERROR(err.cast_unsigned())),
                Some(
                    ERROR_INVALID_PARAMETER
                        | ERROR_INVALID_NAME
                        | ERROR_NOT_A_REPARSE_POINT
                        | ERROR_INVALID_REPARSE_DATA
                )
            ) =>
        {
            // Broken reparse point.
            let _ = fs_err::remove_dir(path);
            Err(create_result.err().unwrap_or(err))
        }
        Err(err) => Err(create_result.err().unwrap_or(err)),
    }
}

/// Create a directory link at `dst` pointing to `src`, replacing any existing link.
///
/// On Windows, this normally creates an NTFS junction, since junctions don't
/// require elevated privileges. When running under Wine, which doesn't implement
/// the reparse-point ioctl that junction creation depends on, this transparently
/// creates a Windows directory symbolic link instead via `CreateSymbolicLinkW`
/// (Wine maps that to a Unix symlink, so it succeeds without privileges).
///
/// The operation is _not_ atomic: any existing entry at `dst` is removed first,
/// then the new link is created at the same path.
///
/// Note that the source must be a directory.
///
/// Changes to this function should be reflected in [`create_symlink`].
#[cfg(windows)]
pub fn replace_symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io::Result<()> {
    let src = src.as_ref();
    let dst = dst.as_ref();

    if src.is_file() {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            format!(
                "Cannot create a directory link for {}: is not a directory",
                src.display()
            ),
        ));
    }

    if uv_windows::is_wine() {
        replace_with_symlink_dir(src, dst)
    } else {
        replace_with_junction(src, dst)
    }
}

#[cfg(windows)]
fn replace_with_junction(src: &Path, dst: &Path) -> std::io::Result<()> {
    // Remove the existing junction, if any.
    match fs_err::remove_dir(dst) {
        Ok(()) => {}
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
        Err(err) => return Err(err),
    }

    // Replace it with a new junction.
    create_junction(src, dst)
}

#[cfg(windows)]
fn replace_with_symlink_dir(src: &Path, dst: &Path) -> std::io::Result<()> {
    // Best-effort removal of any existing entry. The destination may be a
    // directory, file, or symlink, so try the directory removal first and
    // fall back to file removal if that fails.
    match fs_err::remove_dir_all(dst) {
        Ok(()) => {}
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
        Err(_) => match fs_err::remove_file(dst) {
            Ok(()) => {}
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
            Err(err) => return Err(err),
        },
    }

    fs_err::os::windows::fs::symlink_dir(dunce::simplified(src), dunce::simplified(dst))
}

/// Create a symlink at `dst` pointing to `src`, replacing any existing symlink if necessary.
///
/// On Unix, this method creates a temporary file, then moves it into place.
#[cfg(unix)]
pub fn replace_symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io::Result<()> {
    // Attempt to create the symlink directly.
    match fs_err::os::unix::fs::symlink(src.as_ref(), dst.as_ref()) {
        Ok(()) => Ok(()),
        Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => {
            // Create a symlink, using a temporary file to ensure atomicity.
            let temp_dir = tempfile::tempdir_in(dst.as_ref().parent().unwrap())?;
            let temp_file = temp_dir.path().join("link");
            fs_err::os::unix::fs::symlink(src, &temp_file)?;

            // Move the symlink into the target location.
            fs_err::rename(&temp_file, dst.as_ref())?;

            Ok(())
        }
        Err(err) => Err(err),
    }
}

/// Create a directory link at `dst` pointing to `src`.
///
/// On Windows, this normally creates an NTFS junction, falling back to a Windows
/// directory symbolic link when running under Wine. See [`replace_symlink`] for
/// the rationale.
///
/// Note that the source must be a directory.
///
/// Changes to this function should be reflected in [`replace_symlink`].
#[cfg(windows)]
pub fn create_symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io::Result<()> {
    let src = src.as_ref();
    let dst = dst.as_ref();

    if src.is_file() {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            format!(
                "Cannot create a directory link for {}: is not a directory",
                src.display()
            ),
        ));
    }

    if uv_windows::is_wine() {
        fs_err::os::windows::fs::symlink_dir(dunce::simplified(src), dunce::simplified(dst))
    } else {
        create_junction(src, dst)
    }
}

/// Create a symlink at `dst` pointing to `src`.
#[cfg(unix)]
pub fn create_symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io::Result<()> {
    fs_err::os::unix::fs::symlink(src.as_ref(), dst.as_ref())
}

/// Remove a symbolic link at `path` without following its target.
pub fn remove_symlink(path: impl AsRef<Path>) -> io::Result<()> {
    let path = path.as_ref();

    #[cfg(windows)]
    {
        use std::os::windows::fs::FileTypeExt;

        if fs_err::symlink_metadata(path)?.file_type().is_symlink_dir() {
            return fs_err::remove_dir(path);
        }
    }

    fs_err::remove_file(path)
}

#[cfg(all(test, windows))]
mod windows_tests {
    use std::assert_matches;
    use std::os::windows::ffi::OsStrExt;

    use super::*;

    #[test]
    fn fs_err_read_link_reads_created_directory_link() -> std::io::Result<()> {
        let tempdir = tempfile::tempdir()?;
        let target = tempdir.path().join("target");
        fs_err::create_dir(&target)?;
        let link = tempdir.path().join("link");

        create_symlink(&target, &link)?;

        assert_eq!(
            verbatim_path(&fs_err::read_link(&link)?),
            verbatim_path(&target)
        );
        Ok(())
    }

    #[test]
    fn fs_err_read_link_reads_long_junction_target() -> std::io::Result<()> {
        let tempdir = tempfile::tempdir()?;
        let mut target = tempdir.path().join("target");
        while target.as_os_str().encode_wide().count() < 257 {
            target.push("long-path-component");
        }
        fs_err::create_dir_all(&target)?;
        let link = tempdir.path().join("link");

        create_symlink(&target, &link)?;

        let link_target = fs_err::read_link(&link)?;
        assert_eq!(verbatim_path(&link_target), verbatim_path(&target));
        Ok(())
    }

    #[test]
    fn create_junction_from_smb_failure_removes_directory() -> std::io::Result<()> {
        #[expect(clippy::print_stderr)]
        let Some(smb_fs) = std::env::var(uv_static::EnvVars::UV_INTERNAL__TEST_SMB_FS).ok() else {
            eprintln!("Skipping: UV_INTERNAL__TEST_SMB_FS not set");
            return Ok(());
        };
        fs_err::create_dir_all(&smb_fs)?;
        let alt_tempdir = tempfile::tempdir_in(smb_fs)?;
        let tempdir = tempfile::tempdir()?;
        let link = tempdir.path().join("link");
        let target = alt_tempdir.path().join("target");
        fs_err::create_dir(&target)?;

        let err = create_junction(&target, &link).unwrap_err();
        assert_eq!(err.kind(), std::io::ErrorKind::InvalidFilename);
        assert_matches!(
            fs_err::symlink_metadata(&link),
            Err(err) if err.kind() == std::io::ErrorKind::NotFound
        );
        Ok(())
    }
}

/// Create a symlink at `dst` pointing to `src` on Unix or copy `src` to `dst` on Windows
///
/// This does not replace an existing symlink or file at `dst`.
///
/// This does not fallback to copying on Unix.
///
/// This function should only be used for files. If targeting a directory, use [`replace_symlink`]
/// instead; it will use a junction on Windows, which is more performant.
pub fn symlink_or_copy_file(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io::Result<()> {
    cfg_select! {
        windows => {
            fs_err::copy(src.as_ref(), dst.as_ref())?;
        },
        unix => {
            fs_err::os::unix::fs::symlink(src.as_ref(), dst.as_ref())?;
        },
    }

    Ok(())
}

/// Return a [`NamedTempFile`] in the specified directory.
///
/// Sets the permissions of the temporary file to `0o666`, to match the non-temporary file default.
/// ([`NamedTempfile`] defaults to `0o600`.)
#[cfg(unix)]
pub fn tempfile_in(path: &Path) -> std::io::Result<NamedTempFile> {
    use std::os::unix::fs::PermissionsExt;
    tempfile::Builder::new()
        .permissions(std::fs::Permissions::from_mode(0o666))
        .tempfile_in(path)
}

/// Return a [`NamedTempFile`] in the specified directory.
#[cfg(not(unix))]
pub fn tempfile_in(path: &Path) -> std::io::Result<NamedTempFile> {
    tempfile::Builder::new().tempfile_in(path)
}

/// Write `data` to `path` atomically using a temporary file and atomic rename.
#[cfg(feature = "tokio")]
pub async fn write_atomic(path: impl AsRef<Path>, data: impl AsRef<[u8]>) -> std::io::Result<()> {
    let temp_file = tempfile_in(
        path.as_ref()
            .parent()
            .expect("Write path must have a parent"),
    )?;
    fs_err::tokio::write(&temp_file, &data).await?;
    persist_with_retry(temp_file, path.as_ref()).await
}

/// Write `data` to `path` atomically using a temporary file and atomic rename.
pub fn write_atomic_sync(path: impl AsRef<Path>, data: impl AsRef<[u8]>) -> std::io::Result<()> {
    let temp_file = tempfile_in(
        path.as_ref()
            .parent()
            .expect("Write path must have a parent"),
    )?;
    fs_err::write(&temp_file, &data)?;
    persist_with_retry_sync(temp_file, path.as_ref())
}

/// Copy `from` to `to` atomically using a temporary file and atomic rename.
pub fn copy_atomic_sync(from: impl AsRef<Path>, to: impl AsRef<Path>) -> std::io::Result<()> {
    let temp_file = tempfile_in(to.as_ref().parent().expect("Write path must have a parent"))?;
    fs_err::copy(from.as_ref(), &temp_file)?;
    persist_with_retry_sync(temp_file, to.as_ref())
}

#[cfg(windows)]
fn backoff_file_move() -> backon::ExponentialBackoff {
    use backon::BackoffBuilder;
    // This amounts to 10 total seconds of trying the operation.
    // We retry 10 times, starting at 10*(2^0) milliseconds for the first retry, doubling with each
    // retry, so the last (10th) one will take about 10*(2^9) milliseconds ~= 5 seconds. All other
    // attempts combined should equal the length of the last attempt (because it's a sum of powers
    // of 2), so 10 seconds overall.
    backon::ExponentialBuilder::default()
        .with_min_delay(std::time::Duration::from_millis(10))
        .with_max_times(10)
        .build()
}

/// Rename a file, retrying (on Windows) if it fails due to transient operating system errors.
#[cfg(feature = "tokio")]
pub async fn rename_with_retry(
    from: impl AsRef<Path>,
    to: impl AsRef<Path>,
) -> Result<(), std::io::Error> {
    #[cfg(windows)]
    {
        use backon::Retryable;
        // On Windows, antivirus software can lock files temporarily, making them inaccessible.
        // This is most common for DLLs, and the common suggestion is to retry the operation with
        // some backoff.
        //
        // See: <https://github.com/astral-sh/uv/issues/1491> & <https://github.com/astral-sh/uv/issues/9531>
        let from = from.as_ref();
        let to = to.as_ref();

        let rename = async || fs_err::rename(from, to);

        rename
            .retry(backoff_file_move())
            .sleep(tokio::time::sleep)
            .when(|e| e.kind() == std::io::ErrorKind::PermissionDenied)
            .notify(|err, _dur| {
                warn!(
                    "Retrying rename from {} to {} due to transient error: {}",
                    from.display(),
                    to.display(),
                    err
                );
            })
            .await
    }
    #[cfg(not(windows))]
    {
        fs_err::tokio::rename(from, to).await
    }
}

// TODO(zanieb): Look into reusing this code?
/// Wrap an arbitrary operation on two files, e.g., copying, with retries on transient operating
/// system errors.
#[cfg_attr(not(windows), allow(unused_variables))]
pub fn with_retry_sync(
    from: impl AsRef<Path>,
    to: impl AsRef<Path>,
    operation_name: &str,
    operation: impl Fn() -> Result<(), std::io::Error>,
) -> Result<(), std::io::Error> {
    #[cfg(windows)]
    {
        use backon::BlockingRetryable;
        // On Windows, antivirus software can lock files temporarily, making them inaccessible.
        // This is most common for DLLs, and the common suggestion is to retry the operation with
        // some backoff.
        //
        // See: <https://github.com/astral-sh/uv/issues/1491> & <https://github.com/astral-sh/uv/issues/9531>
        let from = from.as_ref();
        let to = to.as_ref();

        operation
            .retry(backoff_file_move())
            .sleep(std::thread::sleep)
            .when(|err| err.kind() == std::io::ErrorKind::PermissionDenied)
            .notify(|err, _dur| {
                warn!(
                    "Retrying {} from {} to {} due to transient error: {}",
                    operation_name,
                    from.display(),
                    to.display(),
                    err
                );
            })
            .call()
            .map_err(|err| {
                std::io::Error::other(format!(
                    "Failed {} {} to {}: {}",
                    operation_name,
                    from.display(),
                    to.display(),
                    err
                ))
            })
    }
    #[cfg(not(windows))]
    {
        operation()
    }
}

/// Why a file persist failed
#[cfg(windows)]
enum PersistRetryError {
    /// Something went wrong while persisting, maybe retry (contains error message)
    Persist(String),
    /// Something went wrong trying to retrieve the file to persist, we must bail
    LostState,
}

/// Persist a `NamedTempFile`, retrying (on Windows) if it fails due to transient operating system
/// errors.
#[cfg(feature = "tokio")]
async fn persist_with_retry(
    from: NamedTempFile,
    to: impl AsRef<Path>,
) -> Result<(), std::io::Error> {
    #[cfg(windows)]
    {
        use backon::Retryable;
        // On Windows, antivirus software can lock files temporarily, making them inaccessible.
        // This is most common for DLLs, and the common suggestion is to retry the operation with
        // some backoff.
        //
        // See: <https://github.com/astral-sh/uv/issues/1491> & <https://github.com/astral-sh/uv/issues/9531>
        let to = to.as_ref();

        // Ok there's a lot of complex ownership stuff going on here.
        //
        // the `NamedTempFile` `persist` method consumes `self`, and returns it back inside
        // the Error in case of `PersistError`:
        // https://docs.rs/tempfile/latest/tempfile/struct.NamedTempFile.html#method.persist
        // So every time we fail, we need to reset the `NamedTempFile` to try again.
        //
        // Every time we (re)try we call this outer closure (`let persist = ...`), so it needs to
        // be at least a `FnMut` (as opposed to `Fnonce`). However the closure needs to return a
        // totally owned `Future` (so effectively it returns a `FnOnce`).
        //
        // But if the `Future` is totally owned it *necessarily* can't write back the `NamedTempFile`
        // to somewhere the outer `FnMut` can see using references. So we need to use `Arc`s
        // with interior mutability (`Mutex`) to have the closure and all the Futures it creates share
        // a single memory location that the `NamedTempFile` can be shuttled in and out of.
        //
        // In spite of the Mutex all of this code will run logically serially, so there shouldn't be a
        // chance for a race where we try to get the `NamedTempFile` but it's actually None. The code
        // is just written pedantically/robustly.
        let from = std::sync::Arc::new(std::sync::Mutex::new(Some(from)));
        let persist = || {
            // Turn our by-ref-captured Arc into an owned Arc that the Future can capture by-value
            let from2 = from.clone();

            async move {
                let maybe_file: Option<NamedTempFile> = from2
                    .lock()
                    .map_err(|_| PersistRetryError::LostState)?
                    .take();
                if let Some(file) = maybe_file {
                    file.persist(to).map_err(|err| {
                        let error_message: String = err.to_string();
                        // Set back the `NamedTempFile` returned back by the Error
                        if let Ok(mut guard) = from2.lock() {
                            *guard = Some(err.file);
                            PersistRetryError::Persist(error_message)
                        } else {
                            PersistRetryError::LostState
                        }
                    })
                } else {
                    Err(PersistRetryError::LostState)
                }
            }
        };

        let persisted = persist
            .retry(backoff_file_move())
            .sleep(tokio::time::sleep)
            .when(|err| matches!(err, PersistRetryError::Persist(_)))
            .notify(|err, _dur| {
                if let PersistRetryError::Persist(error_message) = err {
                    warn!(
                        "Retrying to persist temporary file to {}: {}",
                        to.display(),
                        error_message,
                    );
                }
            })
            .await;

        match persisted {
            Ok(_) => Ok(()),
            Err(PersistRetryError::Persist(error_message)) => Err(std::io::Error::other(format!(
                "Failed to persist temporary file to {}: {}",
                to.display(),
                error_message,
            ))),
            Err(PersistRetryError::LostState) => Err(std::io::Error::other(format!(
                "Failed to retrieve temporary file while trying to persist to {}",
                to.display()
            ))),
        }
    }
    #[cfg(not(windows))]
    {
        async { fs_err::rename(from, to) }.await
    }
}

/// Persist a `NamedTempFile`, retrying (on Windows) if it fails due to transient operating system
/// errors.
///
/// This is a synchronous implementation of [`persist_with_retry`].
pub fn persist_with_retry_sync(
    from: NamedTempFile,
    to: impl AsRef<Path>,
) -> Result<(), std::io::Error> {
    #[cfg(windows)]
    {
        use backon::BlockingRetryable;
        // On Windows, antivirus software can lock files temporarily, making them inaccessible.
        // This is most common for DLLs, and the common suggestion is to retry the operation with
        // some backoff.
        //
        // See: <https://github.com/astral-sh/uv/issues/1491> & <https://github.com/astral-sh/uv/issues/9531>
        let to = to.as_ref();

        // the `NamedTempFile` `persist` method consumes `self`, and returns it back inside the Error in case of `PersistError`
        // https://docs.rs/tempfile/latest/tempfile/struct.NamedTempFile.html#method.persist
        // So we will update the `from` optional value in safe and borrow-checker friendly way every retry
        // Allows us to use the NamedTempFile inside a FnMut closure used for backoff::retry
        let mut from = Some(from);
        let persist = || {
            // Needed because we cannot move out of `from`, a captured variable in an `FnMut` closure, and then pass it to the async move block
            if let Some(file) = from.take() {
                file.persist(to).map_err(|err| {
                    let error_message = err.to_string();
                    // Set back the NamedTempFile returned back by the Error
                    from = Some(err.file);
                    PersistRetryError::Persist(error_message)
                })
            } else {
                Err(PersistRetryError::LostState)
            }
        };

        let persisted = persist
            .retry(backoff_file_move())
            .sleep(std::thread::sleep)
            .when(|err| matches!(err, PersistRetryError::Persist(_)))
            .notify(|err, _dur| {
                if let PersistRetryError::Persist(error_message) = err {
                    warn!(
                        "Retrying to persist temporary file to {}: {}",
                        to.display(),
                        error_message,
                    );
                }
            })
            .call();

        match persisted {
            Ok(_) => Ok(()),
            Err(PersistRetryError::Persist(error_message)) => Err(std::io::Error::other(format!(
                "Failed to persist temporary file to {}: {}",
                to.display(),
                error_message,
            ))),
            Err(PersistRetryError::LostState) => Err(std::io::Error::other(format!(
                "Failed to retrieve temporary file while trying to persist to {}",
                to.display()
            ))),
        }
    }
    #[cfg(not(windows))]
    {
        fs_err::rename(from, to)
    }
}

/// Iterate over the subdirectories of a directory.
///
/// If the directory does not exist, returns an empty iterator.
pub fn directories(
    path: impl AsRef<Path>,
) -> Result<impl Iterator<Item = PathBuf>, std::io::Error> {
    let entries = match path.as_ref().read_dir() {
        Ok(entries) => Some(entries),
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
        Err(err) => return Err(err),
    };
    Ok(entries
        .into_iter()
        .flatten()
        .filter_map(|entry| match entry {
            Ok(entry) => Some(entry),
            Err(err) => {
                warn!("Failed to read entry: {err}");
                None
            }
        })
        .filter(|entry| entry.file_type().is_ok_and(|file_type| file_type.is_dir()))
        .map(|entry| entry.path()))
}

/// Iterate over the entries in a directory.
///
/// If the directory does not exist, returns an empty iterator.
pub fn entries(path: impl AsRef<Path>) -> Result<impl Iterator<Item = PathBuf>, std::io::Error> {
    let entries = match path.as_ref().read_dir() {
        Ok(entries) => Some(entries),
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
        Err(err) => return Err(err),
    };
    Ok(entries
        .into_iter()
        .flatten()
        .filter_map(|entry| match entry {
            Ok(entry) => Some(entry),
            Err(err) => {
                warn!("Failed to read entry: {err}");
                None
            }
        })
        .map(|entry| entry.path()))
}

/// Iterate over the files in a directory.
///
/// If the directory does not exist, returns an empty iterator.
pub fn files(path: impl AsRef<Path>) -> Result<impl Iterator<Item = PathBuf>, std::io::Error> {
    let entries = match path.as_ref().read_dir() {
        Ok(entries) => Some(entries),
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
        Err(err) => return Err(err),
    };
    Ok(entries
        .into_iter()
        .flatten()
        .filter_map(|entry| match entry {
            Ok(entry) => Some(entry),
            Err(err) => {
                warn!("Failed to read entry: {err}");
                None
            }
        })
        .filter(|entry| entry.file_type().is_ok_and(|file_type| file_type.is_file()))
        .map(|entry| entry.path()))
}

/// Returns `true` if a path is a temporary file or directory.
pub fn is_temporary(path: impl AsRef<Path>) -> bool {
    path.as_ref()
        .file_name()
        .and_then(|name| name.to_str())
        .is_some_and(|name| name.starts_with(".tmp"))
}

/// Checks if the grandparent directory of the given executable is the base
/// of a virtual environment.
///
/// The procedure described in PEP 405 includes checking both the parent and
/// grandparent directory of an executable, but in practice we've found this to
/// be unnecessary.
pub fn is_virtualenv_executable(executable: impl AsRef<Path>) -> bool {
    executable
        .as_ref()
        .parent()
        .and_then(Path::parent)
        .is_some_and(is_virtualenv_base)
}

/// Returns `true` if a path is the base path of a virtual environment,
/// indicated by the presence of a `pyvenv.cfg` file.
///
/// The procedure described in PEP 405 includes scanning `pyvenv.cfg`
/// for a `home` key, but in practice we've found this to be
/// unnecessary.
pub fn is_virtualenv_base(path: impl AsRef<Path>) -> bool {
    path.as_ref().join("pyvenv.cfg").is_file()
}

/// Whether the error is due to a lock being held.
fn is_known_already_locked_error(err: &std::fs::TryLockError) -> bool {
    match err {
        std::fs::TryLockError::WouldBlock => true,
        std::fs::TryLockError::Error(err) => {
            // On Windows, we've seen: Os { code: 33, kind: Uncategorized, message: "The process cannot access the file because another process has locked a portion of the file." }
            if cfg!(windows) && err.raw_os_error() == Some(33) {
                return true;
            }
            false
        }
    }
}

/// An asynchronous reader that reports progress as bytes are read.
#[cfg(feature = "tokio")]
pub struct ProgressReader<Reader: tokio::io::AsyncRead + Unpin, Callback: Fn(usize) + Unpin> {
    reader: Reader,
    callback: Callback,
}

#[cfg(feature = "tokio")]
impl<Reader: tokio::io::AsyncRead + Unpin, Callback: Fn(usize) + Unpin>
    ProgressReader<Reader, Callback>
{
    /// Create a new [`ProgressReader`] that wraps another reader.
    pub fn new(reader: Reader, callback: Callback) -> Self {
        Self { reader, callback }
    }
}

#[cfg(feature = "tokio")]
impl<Reader: tokio::io::AsyncRead + Unpin, Callback: Fn(usize) + Unpin> tokio::io::AsyncRead
    for ProgressReader<Reader, Callback>
{
    fn poll_read(
        mut self: std::pin::Pin<&mut Self>,
        cx: &mut std::task::Context<'_>,
        buf: &mut tokio::io::ReadBuf<'_>,
    ) -> std::task::Poll<std::io::Result<()>> {
        std::pin::Pin::new(&mut self.as_mut().reader)
            .poll_read(cx, buf)
            .map_ok(|()| {
                (self.callback)(buf.filled().len());
            })
    }
}

/// Recursively copy a directory and its contents.
pub fn copy_dir_all(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io::Result<()> {
    fs_err::create_dir_all(&dst)?;
    for entry in fs_err::read_dir(src.as_ref())? {
        let entry = entry?;
        let ty = entry.file_type()?;
        if ty.is_dir() {
            copy_dir_all(entry.path(), dst.as_ref().join(entry.file_name()))?;
        } else {
            fs_err::copy(entry.path(), dst.as_ref().join(entry.file_name()))?;
        }
    }
    Ok(())
}

/// Perform a safe removal of a virtual environment.
///
/// The link or file at `location` is removed without following it.
pub fn remove_virtualenv(location: &Path) -> io::Result<()> {
    if !fs_err::symlink_metadata(location)?.is_dir() {
        return remove_symlink(location);
    }

    // On Windows, if the current executable is in the directory, defer self-deletion since Windows
    // won't let you unlink a running executable.
    #[cfg(windows)]
    if let Ok(itself) = std::env::current_exe() {
        let target = std::path::absolute(location)?;
        if itself.starts_with(&target) {
            debug!("Detected self-delete of executable: {}", itself.display());
            self_replace::self_delete_outside_path(location)?;
        }
    }

    // We defer removal of the `pyvenv.cfg` until the end, so if we fail to remove the environment,
    // uv can still identify it as a Python virtual environment that can be deleted.
    for entry in fs_err::read_dir(location)? {
        let entry = entry?;
        let path = entry.path();
        if path == location.join("pyvenv.cfg") {
            continue;
        }
        if path.is_dir() {
            fs_err::remove_dir_all(&path)?;
        } else {
            fs_err::remove_file(&path)?;
        }
    }

    match fs_err::remove_file(location.join("pyvenv.cfg")) {
        Ok(()) => {}
        Err(err) if err.kind() == io::ErrorKind::NotFound => {}
        Err(err) => return Err(err),
    }

    // Remove the virtual environment directory itself
    match fs_err::remove_dir_all(location) {
        Ok(()) => {}
        Err(err) if err.kind() == io::ErrorKind::NotFound => {}
        // If the virtual environment is a mounted file system, e.g., in a Docker container, we
        // cannot delete it — but that doesn't need to be a fatal error
        Err(err) if err.kind() == io::ErrorKind::ResourceBusy => {
            debug!(
                "Skipping removal of `{}` directory due to {err}",
                location.display(),
            );
        }
        Err(err) => return Err(err),
    }

    Ok(())
}

/// Prepare an empty virtual environment directory, resolving links when possible.
///
/// Returns whether an existing entry was found.
pub fn clear_virtualenv(location: &Path) -> io::Result<bool> {
    let location = location
        .canonicalize()
        .unwrap_or_else(|_| location.to_path_buf());
    let cleared = match remove_virtualenv(&location) {
        Ok(()) => true,
        Err(err) if err.kind() == io::ErrorKind::NotFound => false,
        Err(err) => return Err(err),
    };
    fs_err::create_dir_all(location)?;
    Ok(cleared)
}

#[cfg(test)]
mod tests {
    use std::assert_matches;

    use super::*;

    #[test]
    fn remove_symlink_removes_directory_link_without_removing_target() -> io::Result<()> {
        let tempdir = tempfile::tempdir()?;
        let target = tempdir.path().join("target");
        fs_err::create_dir(&target)?;
        fs_err::write(target.join("file"), "content")?;
        let link = tempdir.path().join("link");

        create_symlink(&target, &link)?;
        remove_symlink(&link)?;

        assert_matches!(
            fs_err::symlink_metadata(&link),
            Err(err) if err.kind() == io::ErrorKind::NotFound
        );
        assert_eq!(fs_err::read_to_string(target.join("file"))?, "content");
        Ok(())
    }

    #[test]
    fn remove_virtualenv_removes_directory_link_without_removing_target() -> io::Result<()> {
        let tempdir = tempfile::tempdir()?;
        let target = tempdir.path().join("target");
        fs_err::create_dir(&target)?;
        let marker = target.join("marker");
        fs_err::write(&marker, "")?;
        let environment = tempdir.path().join("environment");
        create_symlink(&target, &environment)?;

        remove_virtualenv(&environment)?;

        assert_matches!(
            fs_err::symlink_metadata(environment),
            Err(err) if err.kind() == io::ErrorKind::NotFound
        );
        assert!(marker.is_file());
        Ok(())
    }

    #[test]
    fn clear_virtualenv_recreates_missing_directory() -> io::Result<()> {
        let tempdir = tempfile::tempdir()?;
        let environment = tempdir.path().join("environment");

        assert!(!clear_virtualenv(&environment)?);
        assert!(environment.is_dir());
        Ok(())
    }
}