vivacity_core/
clone.rs

1//! Clone of a store tree into vendor/, the hot path of the install.
2//! macOS/APFS: `clonefile(2)` of the whole directory (one syscall, copy-on-write,
3//! measured 8x faster than extraction in M0). Elsewhere, or if clonefile
4//! fails (other FS, different volume): recursive walk with hardlinks (pnpm
5//! model), and a real copy as a last resort. Always towards an ABSENT
6//! destination (the caller removes the previous version first), so no mixed
7//! states.
8
9use crate::error::{Error, Result};
10use std::path::Path;
11
12pub fn clone_tree(src: &Path, dst: &Path) -> Result<()> {
13    if let Some(parent) = dst.parent() {
14        std::fs::create_dir_all(parent).map_err(Error::io(parent))?;
15    }
16
17    #[cfg(target_os = "macos")]
18    {
19        use std::os::unix::ffi::OsStrExt as _;
20        let c_src = std::ffi::CString::new(src.as_os_str().as_bytes());
21        let c_dst = std::ffi::CString::new(dst.as_os_str().as_bytes());
22        if let (Ok(c_src), Ok(c_dst)) = (c_src, c_dst) {
23            // SAFETY: FFI call to clonefile through libc, two valid C strings,
24            // no shared memory.
25            let rc = unsafe { libc::clonefile(c_src.as_ptr(), c_dst.as_ptr(), 0) };
26            if rc == 0 {
27                return Ok(());
28            }
29            // Failure (non-APFS FS, different volumes...): fall through to the next strategies.
30        }
31    }
32
33    link_or_copy_tree(src, dst)
34}
35
36fn link_or_copy_tree(src: &Path, dst: &Path) -> Result<()> {
37    std::fs::create_dir_all(dst).map_err(Error::io(dst))?;
38    for entry in std::fs::read_dir(src).map_err(Error::io(src))? {
39        let entry = entry.map_err(Error::io(src))?;
40        let from = entry.path();
41        let to = dst.join(entry.file_name());
42        let ftype = entry.file_type().map_err(Error::io(&from))?;
43        if ftype.is_dir() {
44            link_or_copy_tree(&from, &to)?;
45        } else if ftype.is_symlink() {
46            let target = std::fs::read_link(&from).map_err(Error::io(&from))?;
47            #[cfg(unix)]
48            symlink_like_unzip(&target, &to)?;
49            #[cfg(windows)]
50            clone_symlink_windows(&from, &target, &to)?;
51            #[cfg(not(any(unix, windows)))]
52            {
53                let _ = target;
54                std::fs::copy(&from, &to).map_err(Error::io(&to))?;
55            }
56        } else {
57            // Linux: try a reflink first (FICLONE, a CoW copy like clonefile
58            // on APFS) — independent of the store so safer than a hardlink,
59            // and a single syscall on btrfs/xfs. On ext4 (no reflink) the
60            // ioctl fails cleanly and we fall back to the hardlink.
61            #[cfg(target_os = "linux")]
62            let done = reflink(&from, &to);
63            #[cfg(not(target_os = "linux"))]
64            let done = false;
65            if !done {
66                // Hardlink first (free); copy if the FS refuses (other volume).
67                if std::fs::hard_link(&from, &to).is_err() {
68                    std::fs::copy(&from, &to).map_err(Error::io(&to))?;
69                }
70            }
71        }
72    }
73    Ok(())
74}
75
76/// Reflink (copy-on-write) `from` → `to` via the FICLONE ioctl. Creates an
77/// independent inode sharing the extents: modifying the clone does not touch
78/// the store. The new file's mode is re-applied from the source (FICLONE
79/// does not copy permissions), to preserve the executable bit of binaries.
80/// Returns false (without leaving a partial file) if the FS does not support
81/// reflink — the caller then falls back to the hardlink.
82#[cfg(target_os = "linux")]
83fn reflink(from: &Path, to: &Path) -> bool {
84    use std::os::unix::io::AsRawFd as _;
85    // Once a filesystem has said it cannot reflink, stop asking: the probe
86    // is an open/create/ioctl/unlink per file, and the answer does not
87    // change within a run (the store and vendor/ stay where they are).
88    static UNSUPPORTED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
89    if UNSUPPORTED.load(std::sync::atomic::Ordering::Relaxed) {
90        return false;
91    }
92    let Ok(src) = std::fs::File::open(from) else {
93        return false;
94    };
95    let dst = match std::fs::OpenOptions::new()
96        .write(true)
97        .create(true)
98        .truncate(true)
99        .open(to)
100    {
101        Ok(f) => f,
102        Err(_) => return false,
103    };
104    // SAFETY: FICLONE ioctl on two valid, open descriptors; no shared
105    // memory. The kernel reads src, writes dst.
106    let rc = unsafe { libc::ioctl(dst.as_raw_fd(), libc::FICLONE, src.as_raw_fd()) };
107    if rc != 0 {
108        let err = std::io::Error::last_os_error();
109        drop(dst);
110        let _ = std::fs::remove_file(to); // empty file created by the open
111                                          // ENOTTY / EOPNOTSUPP / EXDEV / EINVAL: this filesystem (or this
112                                          // pair of filesystems) never will; other errors are per file.
113        if matches!(
114            err.raw_os_error(),
115            Some(libc::ENOTTY) | Some(libc::EOPNOTSUPP) | Some(libc::EXDEV) | Some(libc::EINVAL)
116        ) {
117            UNSUPPORTED.store(true, std::sync::atomic::Ordering::Relaxed);
118        }
119        return false;
120    }
121    if let Ok(meta) = src.metadata() {
122        let _ = std::fs::set_permissions(to, meta.permissions());
123    }
124    true
125}
126
127/// Windows: creating symlinks requires a privilege (Developer Mode or
128/// SeCreateSymbolicLinkPrivilege). We try the real symlink, and failing that
129/// copy the RESOLVED content — the resulting vendor/ is functional but no
130/// longer a link (a parity divergence documented in docs/windows.md). A
131/// dangling link fails loudly instead of vanishing silently.
132#[cfg(windows)]
133fn clone_symlink_windows(from: &Path, target: &Path, to: &Path) -> Result<()> {
134    let is_dir = std::fs::metadata(from).map(|m| m.is_dir()).unwrap_or(false);
135    let made = if is_dir {
136        std::os::windows::fs::symlink_dir(target, to)
137    } else {
138        std::os::windows::fs::symlink_file(target, to)
139    };
140    if made.is_ok() {
141        return Ok(());
142    }
143    if is_dir {
144        link_or_copy_tree(from, to) // read_dir follows the link
145    } else {
146        if std::fs::hard_link(from, to).is_err() {
147            std::fs::copy(from, to).map_err(Error::io(to))?;
148        }
149        Ok(())
150    }
151}
152
153/// A symbolic link the way `unzip` (Composer's extractor) leaves one: on
154/// macOS the link's own mode is 0777 (`fchmodat` without following), where a plain `symlink()`
155/// gets the umask applied; Linux ignores link modes.
156#[cfg(unix)]
157pub fn symlink_like_unzip(target: &std::path::Path, link: &std::path::Path) -> Result<()> {
158    std::os::unix::fs::symlink(target, link).map_err(Error::io(link))?;
159    #[cfg(target_os = "macos")]
160    {
161        use std::os::unix::ffi::OsStrExt;
162        let c = std::ffi::CString::new(link.as_os_str().as_bytes()).map_err(|_| Error::Io {
163            path: link.to_path_buf(),
164            source: std::io::Error::new(std::io::ErrorKind::InvalidInput, "path contains NUL"),
165        })?;
166        // SAFETY: FFI call with a valid NUL-terminated path; no memory is
167        // shared, the return value is checked.
168        let rc =
169            unsafe { libc::fchmodat(libc::AT_FDCWD, c.as_ptr(), 0o777, libc::AT_SYMLINK_NOFOLLOW) };
170        if rc != 0 {
171            return Err(Error::io(link)(std::io::Error::last_os_error()));
172        }
173    }
174    Ok(())
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180
181    #[test]
182    fn clones_files_dirs_symlinks_and_exec_bits() {
183        let tmp = tempfile::tempdir().expect("tmp");
184        let src = tmp.path().join("src");
185        std::fs::create_dir_all(src.join("sub")).expect("mkdir");
186        std::fs::write(src.join("a.txt"), b"hello").expect("write");
187        std::fs::write(src.join("sub/tool"), b"#!/bin/sh\n").expect("write");
188        #[cfg(unix)]
189        {
190            use std::os::unix::fs::PermissionsExt as _;
191            std::fs::set_permissions(src.join("sub/tool"), std::fs::Permissions::from_mode(0o755))
192                .expect("chmod");
193            std::os::unix::fs::symlink("a.txt", src.join("link")).expect("ln");
194        }
195        // Windows: the fixture's link requires Developer Mode or
196        // SeCreateSymbolicLinkPrivilege — without it we cannot build the
197        // fixture, so that portion is announced and then skipped (the copy
198        // fallback of clone_symlink_windows cannot be forced from here).
199        #[cfg(windows)]
200        let with_link = match std::os::windows::fs::symlink_file("a.txt", src.join("link")) {
201            Ok(()) => true,
202            Err(e) => {
203                eprintln!("symlink refused on this host ({e}) — link portion not exercised");
204                false
205            }
206        };
207
208        let dst = tmp.path().join("dst/pkg");
209        clone_tree(&src, &dst).expect("clone");
210        assert_eq!(std::fs::read(dst.join("a.txt")).expect("read"), b"hello");
211        #[cfg(unix)]
212        {
213            use std::os::unix::fs::PermissionsExt as _;
214            let mode = std::fs::metadata(dst.join("sub/tool"))
215                .expect("meta")
216                .permissions()
217                .mode();
218            assert_eq!(mode & 0o111, 0o111, "executable bit lost on clone");
219            assert!(dst
220                .join("link")
221                .symlink_metadata()
222                .expect("meta")
223                .file_type()
224                .is_symlink());
225        }
226        #[cfg(windows)]
227        if with_link {
228            // Never a lost entry: either a real link (privilege present —
229            // the same one that allowed the fixture), or a copy of the
230            // resolved content; in both cases reading yields the target's
231            // content.
232            let meta = dst.join("link").symlink_metadata().expect("entry lost");
233            assert!(
234                meta.file_type().is_symlink() || meta.file_type().is_file(),
235                "neither link nor file"
236            );
237            assert_eq!(std::fs::read(dst.join("link")).expect("read"), b"hello");
238        }
239        // Modifying the clone does not touch the source (CoW or hardlink:
240        // we replace the file, we do not edit it in place).
241        std::fs::write(dst.join("a.txt"), b"changed").expect("write");
242        #[cfg(target_os = "macos")]
243        assert_eq!(std::fs::read(src.join("a.txt")).expect("read"), b"hello");
244    }
245}
vivacity_core/clone.rs

vivacity_core/
clone.rs
