Skip to main content

dir_tree_ops/
lib.rs

1//! Tree operations on directories: copy, move, remove, and size.
2//!
3//! Four operations over `AsRef<Path>` roots, plus progress-reporting variants
4//! for copy and move:
5//!
6//! - [`copy_tree`]: recursive copy with a streaming, iterative walk and no
7//!   whole-tree snapshot. Regular files go through `std::fs::copy`, which
8//!   reaches `clonefile` on APFS and `copy_file_range` on Linux.
9//! - [`move_tree`]: rename first, staged copy fallback when the rename
10//!   cannot apply. The source stays unchanged until the destination is
11//!   complete and durable.
12//! - [`remove_tree`]: recursive remove that treats symlinks as leaves.
13//! - [`tree_size`]: byte lengths of regular files plus symlink target
14//!   lengths. Directories contribute zero, and links are leaves.
15//!
16//! # Destination semantics
17//!
18//! `dst` names the resulting root: `copy_tree("a/src", "b/dest", ..)` makes
19//! `b/dest` a replica of `a/src`. There is no name-appending, so a first and
20//! a second run produce the same shape. The mapping is `src/<rel>` to
21//! `dst/<rel>`, always, matching `rsync -a src/ dst/`. The parent of `dst`
22//! must already exist, and a missing parent is `NotFound` naming the parent.
23//! If `dst` exists as a directory, a copy merges into it with per-entry
24//! conflict handling from [`Options::overwrite`].
25//!
26//! # Overlap
27//!
28//! Every operation resolves both roots before touching anything. `dst` equal
29//! to `src`, `dst` inside `src`, and `src` inside `dst` are all rejected with
30//! `InvalidInput` carrying a [`PathError`] with `op` [`Op::Scan`] and both
31//! paths. Resolution canonicalizes the existing portion of each path, and on
32//! Unix also compares `(dev, ino)` along each path, so a symlink alias or a
33//! bind mount of one root counts as the same tree. Inside the walk, an
34//! existing destination entry is removed only after its identity is checked
35//! against every source entry, and the source is removed only by the last
36//! step of a move.
37//!
38//! # Symlinks
39//!
40//! A symlink copies as a symlink. Every entry is classified through
41//! `symlink_metadata`, the target string is reproduced verbatim (relative
42//! stays relative, absolute stays absolute), and the walker treats each link
43//! as a leaf. A dangling link copies as the same dangling link and is
44//! counted in [`Summary::symlinks`]. [`remove_tree`] deletes a link as a
45//! link, so the tree behind it survives.
46//!
47//! # Move safety
48//!
49//! [`move_tree`] runs in ordered phases: a rename attempt before any read of
50//! the source, then (only on a cross-device failure or when replacing an
51//! existing destination) a staged copy into a hidden sibling of the final
52//! destination with files fsynced and directories fsynced on Unix, a
53//! finalize rename, and only then removal of the source. A failure in any
54//! phase before source removal returns the error with the source unchanged,
55//! the destination as it was, and no hidden sibling left behind. A failure
56//! during source removal reports [`Op::RemoveSource`]. The destination is
57//! already complete at that point, so no bytes are lost and the call can be
58//! retried.
59//!
60//! # Errors
61//!
62//! Every operation returns `std::io::Result`. The `io::ErrorKind` of the
63//! underlying filesystem failure is preserved, and its payload is a [`PathError`]
64//! carrying the operation step and the path (or paths) involved. Downcast via
65//! `err.get_ref()` to read them. Invalid options return `InvalidInput` before
66//! any filesystem access.
67//!
68//! # TOCTOU stance
69//!
70//! There are no `exists()` pre-flight checks: existence is learned from each
71//! operation's own syscall result. Progress copies claim a destination file
72//! with `create_new`. Non-progress copies check the entry just before
73//! `std::fs::copy`, which is required for clone-capable filesystem copying.
74//! Source files open with `O_NOFOLLOW` on Linux, Android, and
75//! the BSD family including macOS. On other Unix targets the open is
76//! followed by an `fstat` identity check against the `symlink_metadata`
77//! taken just before, and on Windows the handle is opened on the reparse
78//! point itself and rejected if it is a link. Each of those fails closed
79//! when an entry is swapped for a link between classification and open. The
80//! fast copy path verifies that the no-follow handle has the identity seen
81//! by the directory scan. `std::fs::copy` then reads the source through its
82//! own path-following open, so after it returns the path is re-opened
83//! no-follow and compared against that handle. On a mismatch, or when the
84//! re-open fails, the new destination file is removed and the call fails
85//! with `InvalidInput`. A swap reverted to the original file before the
86//! re-check is not detected. Full elimination needs `openat`-style
87//! traversal, which std does not portably expose. Residual and documented: a
88//! caller that lets another process replace whole directories on the
89//! traversal path can still redirect descent. Trees under shared writable
90//! parents need stronger isolation than this API provides.
91//!
92//! # Non-goals (v1)
93//!
94//! mtime, ownership, and xattr preservation, a follow-links mode,
95//! cancellation from the progress callback, single-file helpers, and async.
96//! FIFOs, sockets, and device nodes are carried by the rename fast path of a
97//! move and report `io::ErrorKind::Unsupported` naming the path when they
98//! have to be copied.
99
100#![forbid(unsafe_code)]
101#![deny(missing_docs)]
102
103use std::collections::HashSet;
104use std::error::Error as StdError;
105use std::ffi::OsString;
106use std::fmt;
107use std::fs::{self, File, Metadata, OpenOptions};
108use std::io::{self, Read, Write};
109use std::path::{Path, PathBuf};
110use std::sync::atomic::{AtomicU64, Ordering};
111use std::time::{SystemTime, UNIX_EPOCH};
112
113#[cfg(test)]
114mod unit_tests;
115
116/// Options for [`copy_tree`], [`move_tree`], and their progress variants.
117///
118/// Construct with `Options::default()` and adjust fields as needed.
119#[derive(Clone, Debug)]
120pub struct Options {
121    /// Per-entry destination conflict policy. Default: [`Overwrite::Error`].
122    pub overwrite: Overwrite,
123    /// Copy buffer size hint for the progress variants, in bytes.
124    /// Default: `64 * 1024`. A value of zero is treated as one.
125    /// Values above `isize::MAX` return `InvalidInput` from all copy and move
126    /// functions before any filesystem access.
127    pub buffer_size: usize,
128}
129
130impl Default for Options {
131    fn default() -> Self {
132        Options {
133            overwrite: Overwrite::Error,
134            buffer_size: 64 * 1024,
135        }
136    }
137}
138
139/// What to do when a destination entry already exists.
140#[non_exhaustive]
141#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
142pub enum Overwrite {
143    /// An existing destination entry stops the operation with
144    /// `io::ErrorKind::AlreadyExists`.
145    #[default]
146    Error,
147    /// An existing destination entry is left untouched and counted in
148    /// [`Summary::skipped`].
149    Skip,
150    /// An existing destination entry is replaced. Type conflicts resolve by
151    /// removing the destination entry first: a directory tree is removed to
152    /// make room for a file, and a symlink is removed as a link, leaving its
153    /// target untouched.
154    Replace,
155}
156
157/// Counts returned by a completed copy or move.
158///
159/// A move that completed through the rename fast path reports counts taken
160/// from a scan of the moved tree at the destination. A directory that scan
161/// cannot read counts as one directory and its contents are left out.
162#[derive(Clone, Debug, Default, PartialEq, Eq)]
163pub struct Summary {
164    /// Total bytes written to destination regular files.
165    pub bytes_copied: u64,
166    /// Regular files copied.
167    pub files: u64,
168    /// Directories created.
169    pub dirs: u64,
170    /// Symlinks reproduced.
171    pub symlinks: u64,
172    /// Entries left untouched under [`Overwrite::Skip`].
173    pub skipped: u64,
174}
175
176/// A progress snapshot passed to the callback of
177/// [`copy_tree_with_progress`] and [`move_tree_with_progress`].
178#[derive(Debug)]
179pub struct Progress<'a> {
180    /// Bytes copied so far. Non-decreasing across every call of one
181    /// operation, and equal to the returned summary's byte count on success.
182    pub bytes_copied: u64,
183    /// Total regular-file bytes found by the pre-scan. Fixed for the whole
184    /// operation. A tree mutated concurrently can make `bytes_copied` land
185    /// under or over this value. Monotonicity still holds.
186    pub total_bytes: u64,
187    /// Entries (files, directories, symlinks) completed so far.
188    pub entries_done: u64,
189    /// Entries found by the pre-scan. Fixed for the whole operation.
190    pub entries_total: u64,
191    /// The entry being processed when this snapshot was taken. The first
192    /// snapshot of an operation names the destination root.
193    pub current_path: &'a Path,
194}
195
196/// The operation step a [`PathError`] happened in.
197#[derive(Clone, Copy, Debug, PartialEq, Eq)]
198pub enum Op {
199    /// Reading directory entries or entry metadata, and the overlap check.
200    Scan,
201    /// Copying one regular file.
202    CopyFile,
203    /// Creating a directory or applying its permissions.
204    CreateDir,
205    /// Reproducing a symlink.
206    Symlink,
207    /// The rename fast path of a move.
208    Rename,
209    /// Removing the source tree after a move's destination is complete.
210    RemoveSource,
211    /// Removing an entry (during [`remove_tree`] or conflict replacement).
212    RemoveEntry,
213    /// Renaming staging into place at the end of a staged move.
214    Finalize,
215}
216
217impl fmt::Display for Op {
218    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
219        let s = match self {
220            Op::Scan => "scan",
221            Op::CopyFile => "copy file",
222            Op::CreateDir => "create dir",
223            Op::Symlink => "symlink",
224            Op::Rename => "rename",
225            Op::RemoveSource => "remove source",
226            Op::RemoveEntry => "remove entry",
227            Op::Finalize => "finalize",
228        };
229        f.write_str(s)
230    }
231}
232
233/// Downcast target for structured error context.
234///
235/// Filesystem errors returned by this crate are `io::Error` values whose
236/// payload is a `PathError`. Invalid options return an error without path
237/// context. `Display` renders `"<op> <path>[ -> <second>]: <source
238/// error>"`, and `Error::source()` yields the underlying `io::Error`.
239///
240/// ```
241/// use dir_tree_ops::{copy_tree, Options, PathError};
242/// let err = copy_tree("/no/such/tree", "/tmp/out", &Options::default()).unwrap_err();
243/// let ctx: &PathError = err.get_ref().unwrap().downcast_ref().unwrap();
244/// assert!(ctx.path.ends_with("tree"));
245/// ```
246#[derive(Debug)]
247pub struct PathError {
248    /// The step that failed.
249    pub op: Op,
250    /// The path the step was acting on.
251    pub path: PathBuf,
252    /// The other path involved, for steps that take two.
253    pub second_path: Option<PathBuf>,
254    source: io::Error,
255}
256
257impl fmt::Display for PathError {
258    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
259        write!(f, "{} {}", self.op, self.path.display())?;
260        if let Some(second) = &self.second_path {
261            write!(f, " -> {}", second.display())?;
262        }
263        write!(f, ": {}", self.source)
264    }
265}
266
267impl StdError for PathError {
268    fn source(&self) -> Option<&(dyn StdError + 'static)> {
269        Some(&self.source)
270    }
271}
272
273fn wrap(op: Op, path: &Path, second: Option<PathBuf>, source: io::Error) -> io::Error {
274    let kind = source.kind();
275    io::Error::new(
276        kind,
277        PathError {
278            op,
279            path: path.to_path_buf(),
280            second_path: second,
281            source,
282        },
283    )
284}
285
286fn contract(
287    op: Op,
288    path: &Path,
289    second: Option<PathBuf>,
290    kind: io::ErrorKind,
291    msg: &str,
292) -> io::Error {
293    wrap(op, path, second, io::Error::new(kind, msg.to_string()))
294}
295
296/// Raw OS code for a cross-device rename failure (`EXDEV` /
297/// `ERROR_NOT_SAME_DEVICE`), matched directly because
298/// `io::ErrorKind::CrossesDevices` stabilized after the MSRV.
299#[cfg(unix)]
300const CROSS_DEVICE_RAW: i32 = 18;
301#[cfg(windows)]
302const CROSS_DEVICE_RAW: i32 = 17;
303
304/// `O_NOFOLLOW` where its value is known. `None` selects the identity-check
305/// fallback in [`open_source`], so every target has an explicit mechanism.
306#[cfg(all(
307    any(target_os = "linux", target_os = "android"),
308    not(any(
309        target_arch = "mips",
310        target_arch = "mips64",
311        target_arch = "sparc",
312        target_arch = "sparc64"
313    ))
314))]
315const O_NOFOLLOW_FLAG: Option<i32> = Some(0o400000);
316#[cfg(all(
317    any(target_os = "linux", target_os = "android"),
318    any(
319        target_arch = "mips",
320        target_arch = "mips64",
321        target_arch = "sparc",
322        target_arch = "sparc64"
323    )
324))]
325const O_NOFOLLOW_FLAG: Option<i32> = Some(0x20000);
326#[cfg(any(
327    target_os = "macos",
328    target_os = "ios",
329    target_os = "tvos",
330    target_os = "watchos",
331    target_os = "freebsd",
332    target_os = "dragonfly",
333    target_os = "openbsd",
334    target_os = "netbsd"
335))]
336const O_NOFOLLOW_FLAG: Option<i32> = Some(0x0100);
337#[cfg(all(
338    unix,
339    not(any(
340        target_os = "linux",
341        target_os = "android",
342        target_os = "macos",
343        target_os = "ios",
344        target_os = "tvos",
345        target_os = "watchos",
346        target_os = "freebsd",
347        target_os = "dragonfly",
348        target_os = "openbsd",
349        target_os = "netbsd"
350    ))
351))]
352const O_NOFOLLOW_FLAG: Option<i32> = None;
353
354#[cfg(unix)]
355fn file_id(meta: &Metadata) -> (u64, u64) {
356    use std::os::unix::fs::MetadataExt;
357    (meta.dev(), meta.ino())
358}
359
360#[cfg(unix)]
361fn portable_file_id(meta: &Metadata) -> Option<(u64, u64)> {
362    Some(file_id(meta))
363}
364
365#[cfg(windows)]
366fn portable_file_id(_meta: &Metadata) -> Option<(u64, u64)> {
367    None
368}
369
370#[cfg(unix)]
371fn same_file_identity(expected: &Metadata, actual: &Metadata) -> bool {
372    portable_file_id(expected) == portable_file_id(actual)
373}
374
375#[cfg(windows)]
376fn same_file_identity(expected: &Metadata, actual: &Metadata) -> bool {
377    use std::os::windows::fs::MetadataExt;
378    expected.file_attributes() == actual.file_attributes()
379        && expected.creation_time() == actual.creation_time()
380        && expected.last_write_time() == actual.last_write_time()
381        && expected.file_size() == actual.file_size()
382}
383
384/// Open a source regular file for reading without following a symlink at
385/// `path`. Fails closed when the entry is a link or changes identity between
386/// classification and open.
387#[cfg(unix)]
388fn open_source(path: &Path) -> io::Result<File> {
389    use std::os::unix::fs::OpenOptionsExt;
390    let mut opts = OpenOptions::new();
391    opts.read(true);
392    match O_NOFOLLOW_FLAG {
393        Some(flag) => {
394            opts.custom_flags(flag);
395            opts.open(path)
396        }
397        None => {
398            let before = fs::symlink_metadata(path)?;
399            if before.file_type().is_symlink() {
400                return Err(io::Error::new(
401                    io::ErrorKind::InvalidInput,
402                    "source entry is a symlink",
403                ));
404            }
405            let file = opts.open(path)?;
406            if file_id(&file.metadata()?) != file_id(&before) {
407                return Err(io::Error::new(
408                    io::ErrorKind::InvalidInput,
409                    "source entry changed identity between scan and open",
410                ));
411            }
412            Ok(file)
413        }
414    }
415}
416
417#[cfg(windows)]
418fn open_source(path: &Path) -> io::Result<File> {
419    use std::os::windows::fs::OpenOptionsExt;
420    const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
421    let file = OpenOptions::new()
422        .read(true)
423        .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT)
424        .open(path)?;
425    if file.metadata()?.file_type().is_symlink() {
426        return Err(io::Error::new(
427            io::ErrorKind::InvalidInput,
428            "source entry is a symlink",
429        ));
430    }
431    Ok(file)
432}
433
434#[cfg(not(any(unix, windows)))]
435compile_error!(
436    "dir-tree-ops needs a no-follow source open, which is defined for Unix and Windows only"
437);
438
439/// Confirm that `sp` still names the file `checked` was opened on before
440/// `std::fs::copy` ran. The copy reads the source through its own
441/// path-following open, so a path swapped to a symlink after the pre-copy
442/// check would feed it foreign bytes. Re-open no-follow and compare
443/// identity against the held handle. A reopen failure or a mismatch is a
444/// swap and fails closed as `InvalidInput`. The caller removes the
445/// destination file on that error.
446fn confirm_copied_source(sp: &Path, checked: &File) -> io::Result<()> {
447    let swapped = || {
448        io::Error::new(
449            io::ErrorKind::InvalidInput,
450            "source entry changed identity during copy",
451        )
452    };
453    let reopened = open_source(sp).map_err(|_| swapped())?;
454    let before = checked.metadata()?;
455    let after = reopened.metadata().map_err(|_| swapped())?;
456    if !same_file_identity(&before, &after) {
457        return Err(swapped());
458    }
459    Ok(())
460}
461
462#[cfg(unix)]
463fn fsync_dir(path: &Path) -> io::Result<()> {
464    File::open(path)?.sync_all()
465}
466
467#[cfg(not(unix))]
468fn fsync_dir(_path: &Path) -> io::Result<()> {
469    Ok(())
470}
471
472#[cfg(unix)]
473fn make_symlink(target: &Path, link: &Path) -> io::Result<()> {
474    std::os::unix::fs::symlink(target, link)
475}
476
477#[cfg(windows)]
478fn make_symlink(target: &Path, link: &Path) -> io::Result<()> {
479    use std::os::windows::fs as wfs;
480    let resolved = match link.parent() {
481        Some(parent) => parent.join(target),
482        None => target.to_path_buf(),
483    };
484    match fs::metadata(&resolved) {
485        Ok(meta) if meta.is_dir() => wfs::symlink_dir(target, link),
486        _ => wfs::symlink_file(target, link),
487    }
488}
489
490fn nonce() -> u64 {
491    static COUNTER: AtomicU64 = AtomicU64::new(0);
492    let t = SystemTime::now()
493        .duration_since(UNIX_EPOCH)
494        .map(|d| u64::from(d.subsec_nanos()) ^ d.as_secs())
495        .unwrap_or(0);
496    t ^ COUNTER
497        .fetch_add(1, Ordering::Relaxed)
498        .wrapping_mul(0x9E37_79B9_7F4A_7C15)
499}
500
501fn call_tag() -> String {
502    format!("{}.{:x}", std::process::id(), nonce())
503}
504
505/// A short hidden sibling name that stays valid when `dst` is at `NAME_MAX`.
506fn hidden_sibling_name(tag: &str, ext: &str) -> OsString {
507    let mut s = OsString::from(".");
508    s.push(tag);
509    s.push(".");
510    s.push(ext);
511    s
512}
513
514/// Canonicalize the longest existing prefix of `p` and append the rest.
515fn resolve_existing(p: &Path) -> PathBuf {
516    let mut cur = p.to_path_buf();
517    let mut tail: Vec<OsString> = Vec::new();
518    loop {
519        match cur.canonicalize() {
520            Ok(mut resolved) => {
521                for part in tail.iter().rev() {
522                    resolved.push(part);
523                }
524                return resolved;
525            }
526            Err(_) => {
527                let name = match cur.file_name() {
528                    Some(n) => n.to_os_string(),
529                    None => return p.to_path_buf(),
530                };
531                let parent = match cur.parent() {
532                    Some(par) if !par.as_os_str().is_empty() => par.to_path_buf(),
533                    Some(_) => PathBuf::from("."),
534                    None => return p.to_path_buf(),
535                };
536                tail.push(name);
537                cur = parent;
538            }
539        }
540    }
541}
542
543/// True when some ancestor-or-self of `path` has the identity `id`.
544#[cfg(unix)]
545fn path_has_ancestor_id(path: &Path, id: (u64, u64)) -> bool {
546    path.ancestors()
547        .any(|a| fs::metadata(a).map(|m| file_id(&m) == id).unwrap_or(false))
548}
549
550#[cfg(unix)]
551fn aliased_by_identity(
552    src_meta: &Metadata,
553    src_resolved: &Path,
554    dst: &Path,
555    dst_resolved: &Path,
556) -> bool {
557    if path_has_ancestor_id(dst_resolved, file_id(src_meta)) {
558        return true;
559    }
560    match fs::metadata(dst) {
561        Ok(dst_meta) => path_has_ancestor_id(src_resolved, file_id(&dst_meta)),
562        Err(_) => false,
563    }
564}
565
566#[cfg(not(unix))]
567fn aliased_by_identity(_: &Metadata, _: &Path, _: &Path, _: &Path) -> bool {
568    false
569}
570
571/// Reject every aliasing relationship between the two roots before any
572/// mutation: equal, either inside the other, by path after resolving the
573/// existing portion and (Unix) by `(dev, ino)` along each path.
574fn overlap_guard(src: &Path, src_meta: &Metadata, dst: &Path) -> io::Result<Option<Metadata>> {
575    if src != dst && src.parent() == dst.parent() {
576        match fs::symlink_metadata(dst) {
577            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(None),
578            Ok(meta) if meta.is_dir() && portable_file_id(&meta) != portable_file_id(src_meta) => {
579                return Ok(Some(meta));
580            }
581            _ => {}
582        }
583    }
584    let s = resolve_existing(src);
585    let d = resolve_existing(dst);
586    let aliased =
587        d.starts_with(&s) || s.starts_with(&d) || aliased_by_identity(src_meta, &s, dst, &d);
588    if aliased {
589        return Err(contract(
590            Op::Scan,
591            dst,
592            Some(src.to_path_buf()),
593            io::ErrorKind::InvalidInput,
594            "source and destination overlap: equal, nested, or aliased",
595        ));
596    }
597    Ok(None)
598}
599
600/// Identities of every source entry. Existing destination entries are checked
601/// against this set before mutation and again before each replacement.
602struct SourceGuard {
603    src: PathBuf,
604    root_id: Option<(u64, u64)>,
605    ids: Option<HashSet<(u64, u64)>>,
606}
607
608impl SourceGuard {
609    fn new(src: &Path, src_meta: &Metadata) -> Self {
610        SourceGuard {
611            src: src.to_path_buf(),
612            root_id: portable_file_id(src_meta),
613            ids: None,
614        }
615    }
616
617    fn collect_source_identities(&mut self) -> io::Result<()> {
618        let mut ids = HashSet::new();
619        if let Some(root_id) = self.root_id {
620            ids.insert(root_id);
621        }
622        self.ids = Some(ids);
623        let src = self.src.clone();
624        let mut stack = vec![src];
625        while let Some(dir) = stack.pop() {
626            let entries = read_dir(&dir)?;
627            for entry in entries {
628                let entry = entry.map_err(|e| wrap(Op::Scan, &dir, None, e))?;
629                let path = entry.path();
630                let meta =
631                    fs::symlink_metadata(&path).map_err(|e| wrap(Op::Scan, &path, None, e))?;
632                self.add_identity(&meta);
633                if meta.is_dir() {
634                    stack.push(path);
635                }
636            }
637        }
638        Ok(())
639    }
640
641    fn add_identity(&mut self, meta: &Metadata) {
642        if let (Some(ids), Some(id)) = (&mut self.ids, portable_file_id(meta)) {
643            ids.insert(id);
644        }
645    }
646
647    /// Reject any existing destination entry that aliases a source entry.
648    /// This pass completes before the first destination mutation.
649    fn preflight_destination(&mut self, dst: &Path) -> io::Result<()> {
650        let root_meta = match fs::symlink_metadata(dst) {
651            Ok(meta) => meta,
652            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(()),
653            Err(e) => return Err(wrap(Op::Scan, dst, None, e)),
654        };
655        self.collect_source_identities()?;
656        self.check(dst, &root_meta)?;
657        if !root_meta.is_dir() {
658            return Ok(());
659        }
660        let mut stack = vec![dst.to_path_buf()];
661        while let Some(dir) = stack.pop() {
662            let entries = read_dir(&dir)?;
663            for entry in entries {
664                let entry = entry.map_err(|e| wrap(Op::Scan, &dir, None, e))?;
665                let path = entry.path();
666                let meta =
667                    fs::symlink_metadata(&path).map_err(|e| wrap(Op::Scan, &path, None, e))?;
668                self.check(&path, &meta)?;
669                if meta.is_dir() {
670                    stack.push(path);
671                }
672            }
673        }
674        Ok(())
675    }
676
677    fn check(&self, path: &Path, meta: &Metadata) -> io::Result<()> {
678        if portable_file_id(meta)
679            .map(|id| {
680                self.root_id == Some(id)
681                    || self
682                        .ids
683                        .as_ref()
684                        .map(|ids| ids.contains(&id))
685                        .unwrap_or(false)
686            })
687            .unwrap_or(false)
688        {
689            return Err(contract(
690                Op::Scan,
691                path,
692                Some(self.src.clone()),
693                io::ErrorKind::InvalidInput,
694                "destination entry aliases the source tree",
695            ));
696        }
697        Ok(())
698    }
699
700    /// Remove an existing destination entry with the primitive for its type.
701    /// `path` is always a path the walker built under `dst`.
702    fn remove_dest_entry(&self, path: &Path) -> io::Result<()> {
703        let meta = match fs::symlink_metadata(path) {
704            Ok(meta) => meta,
705            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(()),
706            Err(e) => return Err(wrap(Op::Scan, path, None, e)),
707        };
708        self.check(path, &meta)?;
709        if meta.is_dir() {
710            fs::remove_dir_all(path).map_err(|e| wrap(Op::RemoveEntry, path, None, e))
711        } else {
712            fs::remove_file(path).map_err(|e| wrap(Op::RemoveEntry, path, None, e))
713        }
714    }
715}
716
717fn read_dir(path: &Path) -> io::Result<fs::ReadDir> {
718    fs::read_dir(path).map_err(|e| wrap(Op::Scan, path, None, e))
719}
720
721struct ProgressSink<'a> {
722    cb: &'a mut dyn FnMut(&Progress<'_>),
723    bytes_copied: u64,
724    total_bytes: u64,
725    entries_done: u64,
726    entries_total: u64,
727}
728
729impl<'a> ProgressSink<'a> {
730    fn new(cb: &'a mut dyn FnMut(&Progress<'_>), totals: &ScanTotals) -> ProgressSink<'a> {
731        ProgressSink {
732            cb,
733            bytes_copied: 0,
734            total_bytes: totals.bytes,
735            entries_done: 0,
736            entries_total: totals.entries,
737        }
738    }
739
740    fn emit(&mut self, path: &Path) {
741        let snapshot = Progress {
742            bytes_copied: self.bytes_copied,
743            total_bytes: self.total_bytes,
744            entries_done: self.entries_done,
745            entries_total: self.entries_total,
746            current_path: path,
747        };
748        (self.cb)(&snapshot);
749    }
750}
751
752struct ScanTotals {
753    bytes: u64,
754    files: u64,
755    dirs: u64,
756    symlinks: u64,
757    entries: u64,
758}
759
760fn add_bytes(total: u64, amount: u64) -> u64 {
761    total.saturating_add(amount)
762}
763
764impl ScanTotals {
765    fn summary(&self) -> Summary {
766        Summary {
767            bytes_copied: self.bytes,
768            files: self.files,
769            dirs: self.dirs,
770            symlinks: self.symlinks,
771            skipped: 0,
772        }
773    }
774}
775
776/// Iterative pre-scan for progress totals. Counts the root directory
777/// itself. Entry types the copy cannot reproduce are left out of the counts,
778/// and the copy reports them when it reaches them.
779fn scan_tree(root: &Path) -> io::Result<ScanTotals> {
780    let mut totals = ScanTotals {
781        bytes: 0,
782        files: 0,
783        dirs: 1,
784        symlinks: 0,
785        entries: 0,
786    };
787    let mut stack = vec![root.to_path_buf()];
788    while let Some(dir) = stack.pop() {
789        let rd = fs::read_dir(&dir).map_err(|e| wrap(Op::Scan, &dir, None, e))?;
790        for entry in rd {
791            let entry = entry.map_err(|e| wrap(Op::Scan, &dir, None, e))?;
792            let meta = fs::symlink_metadata(entry.path())
793                .map_err(|e| wrap(Op::Scan, &entry.path(), None, e))?;
794            let ft = meta.file_type();
795            if ft.is_symlink() {
796                totals.symlinks += 1;
797            } else if ft.is_dir() {
798                totals.dirs += 1;
799                stack.push(entry.path());
800            } else if ft.is_file() {
801                totals.files += 1;
802                totals.bytes = add_bytes(totals.bytes, meta.len());
803            }
804        }
805    }
806    totals.entries = totals
807        .files
808        .saturating_add(totals.dirs)
809        .saturating_add(totals.symlinks);
810    Ok(totals)
811}
812
813/// Counts for a tree that already arrived by rename. An unreadable directory
814/// counts as one directory.
815fn summarize_moved(root: &Path) -> Summary {
816    let mut summary = Summary {
817        dirs: 1,
818        ..Summary::default()
819    };
820    let mut stack = vec![root.to_path_buf()];
821    while let Some(dir) = stack.pop() {
822        let rd = match fs::read_dir(&dir) {
823            Ok(rd) => rd,
824            Err(_) => continue,
825        };
826        for entry in rd.flatten() {
827            let meta = match fs::symlink_metadata(entry.path()) {
828                Ok(meta) => meta,
829                Err(_) => continue,
830            };
831            let ft = meta.file_type();
832            if ft.is_symlink() {
833                summary.symlinks += 1;
834            } else if ft.is_dir() {
835                summary.dirs += 1;
836                stack.push(entry.path());
837            } else if ft.is_file() {
838                summary.files += 1;
839                summary.bytes_copied = add_bytes(summary.bytes_copied, meta.len());
840            }
841        }
842    }
843    summary
844}
845
846type FileHook<'a> = &'a mut dyn FnMut(u64, &Path) -> io::Result<()>;
847type PathHook<'a> = &'a mut dyn FnMut(&Path) -> io::Result<()>;
848type VoidHook<'a> = &'a mut dyn FnMut();
849
850struct Frame {
851    src: PathBuf,
852    dst: PathBuf,
853    entries: fs::ReadDir,
854    perms: fs::Permissions,
855    created: bool,
856}
857
858struct CopyEngine<'a> {
859    overwrite: Overwrite,
860    fsync: bool,
861    buf: Vec<u8>,
862    summary: Summary,
863    progress: Option<ProgressSink<'a>>,
864    file_hook: Option<FileHook<'a>>,
865    files_seen: u64,
866    guard: SourceGuard,
867}
868
869impl CopyEngine<'_> {
870    fn entry_done(&mut self, path: &Path) {
871        if let Some(sink) = &mut self.progress {
872            sink.entries_done += 1;
873            sink.emit(path);
874        }
875    }
876
877    /// Copy the children of `src_root` into `dst_root`, then apply
878    /// `root_perms` if the caller created the root.
879    fn run(
880        &mut self,
881        src_root: &Path,
882        dst_root: &Path,
883        root_created: bool,
884        root_perms: fs::Permissions,
885    ) -> io::Result<()> {
886        let entries = read_dir(src_root)?;
887        let mut frames = vec![Frame {
888            src: src_root.to_path_buf(),
889            dst: dst_root.to_path_buf(),
890            entries,
891            perms: root_perms,
892            created: root_created,
893        }];
894        while let Some(top) = frames.last_mut() {
895            let next = top.entries.next();
896            match next {
897                None => {
898                    let frame = frames.pop().expect("frame stack non-empty");
899                    if frame.created {
900                        fs::set_permissions(&frame.dst, frame.perms)
901                            .map_err(|e| wrap(Op::CreateDir, &frame.dst, None, e))?;
902                    }
903                    if self.fsync {
904                        fsync_dir(&frame.dst)
905                            .map_err(|e| wrap(Op::CreateDir, &frame.dst, None, e))?;
906                    }
907                    self.entry_done(&frame.dst);
908                }
909                Some(entry) => {
910                    let entry = entry.map_err(|e| {
911                        let top = frames.last().expect("frame stack non-empty");
912                        wrap(Op::Scan, &top.src, None, e)
913                    })?;
914                    let name = entry.file_name();
915                    let (sp, dp) = {
916                        let top = frames.last().expect("frame stack non-empty");
917                        (top.src.join(&name), top.dst.join(&name))
918                    };
919                    let meta =
920                        fs::symlink_metadata(&sp).map_err(|e| wrap(Op::Scan, &sp, None, e))?;
921                    self.guard.add_identity(&meta);
922                    let ft = meta.file_type();
923                    if ft.is_symlink() {
924                        self.copy_symlink(&sp, &dp)?;
925                    } else if ft.is_dir() {
926                        if let Some(frame) = self.enter_dir(&sp, &dp, meta)? {
927                            frames.push(frame);
928                        }
929                    } else if ft.is_file() {
930                        self.copy_file(&sp, &dp, &meta)?;
931                    } else {
932                        return Err(contract(
933                            Op::CopyFile,
934                            &sp,
935                            None,
936                            io::ErrorKind::Unsupported,
937                            "unsupported file type",
938                        ));
939                    }
940                }
941            }
942        }
943        Ok(())
944    }
945
946    fn enter_dir(&mut self, sp: &Path, dp: &Path, meta: Metadata) -> io::Result<Option<Frame>> {
947        let created = match fs::create_dir(dp) {
948            Ok(()) => true,
949            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {
950                let meta = fs::symlink_metadata(dp).map_err(|e2| wrap(Op::Scan, dp, None, e2))?;
951                if meta.is_dir() {
952                    // The source guard cleared this existing directory for merge.
953                    self.guard.check(dp, &meta)?;
954                    false
955                } else {
956                    match self.overwrite {
957                        Overwrite::Error => {
958                            return Err(wrap(Op::CreateDir, dp, Some(sp.to_path_buf()), e))
959                        }
960                        Overwrite::Skip => {
961                            self.summary.skipped += 1;
962                            self.entry_done(dp);
963                            return Ok(None);
964                        }
965                        Overwrite::Replace => {
966                            self.guard.remove_dest_entry(dp)?;
967                            fs::create_dir(dp).map_err(|e2| wrap(Op::CreateDir, dp, None, e2))?;
968                            true
969                        }
970                    }
971                }
972            }
973            Err(e) => return Err(wrap(Op::CreateDir, dp, None, e)),
974        };
975        if created {
976            self.summary.dirs += 1;
977        }
978        let entries = read_dir(sp)?;
979        Ok(Some(Frame {
980            src: sp.to_path_buf(),
981            dst: dp.to_path_buf(),
982            entries,
983            perms: meta.permissions(),
984            created,
985        }))
986    }
987
988    fn copy_symlink(&mut self, sp: &Path, dp: &Path) -> io::Result<()> {
989        let target = fs::read_link(sp).map_err(|e| wrap(Op::Scan, sp, None, e))?;
990        match make_symlink(&target, dp) {
991            Ok(()) => {}
992            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => match self.overwrite {
993                Overwrite::Error => {
994                    return Err(wrap(Op::Symlink, dp, Some(sp.to_path_buf()), e));
995                }
996                Overwrite::Skip => {
997                    self.summary.skipped += 1;
998                    self.entry_done(dp);
999                    return Ok(());
1000                }
1001                Overwrite::Replace => {
1002                    self.guard.remove_dest_entry(dp)?;
1003                    make_symlink(&target, dp)
1004                        .map_err(|e2| wrap(Op::Symlink, dp, Some(sp.to_path_buf()), e2))?;
1005                }
1006            },
1007            Err(e) => return Err(wrap(Op::Symlink, dp, Some(sp.to_path_buf()), e)),
1008        }
1009        self.summary.symlinks += 1;
1010        self.entry_done(dp);
1011        Ok(())
1012    }
1013
1014    /// Claim the destination slot for one file copy with `create_new`.
1015    /// `Ok(None)` means the entry was skipped under [`Overwrite::Skip`].
1016    /// Errors are already wrapped.
1017    fn open_dest(&mut self, sp: &Path, dp: &Path) -> io::Result<Option<File>> {
1018        let create = |dp: &Path| OpenOptions::new().write(true).create_new(true).open(dp);
1019        match create(dp) {
1020            Ok(file) => Ok(Some(file)),
1021            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => match self.overwrite {
1022                Overwrite::Error => Err(wrap(Op::CopyFile, sp, Some(dp.to_path_buf()), e)),
1023                Overwrite::Skip => Ok(None),
1024                Overwrite::Replace => {
1025                    self.guard.remove_dest_entry(dp)?;
1026                    match create(dp) {
1027                        Ok(file) => Ok(Some(file)),
1028                        Err(e2) => Err(wrap(Op::CopyFile, sp, Some(dp.to_path_buf()), e2)),
1029                    }
1030                }
1031            },
1032            Err(e) => Err(wrap(Op::CopyFile, sp, Some(dp.to_path_buf()), e)),
1033        }
1034    }
1035
1036    fn prepare_fast_dest(&mut self, sp: &Path, dp: &Path) -> io::Result<bool> {
1037        match fs::symlink_metadata(dp) {
1038            Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(true),
1039            Err(e) => Err(wrap(Op::Scan, dp, Some(sp.to_path_buf()), e)),
1040            Ok(_) => match self.overwrite {
1041                Overwrite::Error => Err(contract(
1042                    Op::CopyFile,
1043                    sp,
1044                    Some(dp.to_path_buf()),
1045                    io::ErrorKind::AlreadyExists,
1046                    "destination already exists",
1047                )),
1048                Overwrite::Skip => Ok(false),
1049                Overwrite::Replace => {
1050                    self.guard.remove_dest_entry(dp)?;
1051                    Ok(true)
1052                }
1053            },
1054        }
1055    }
1056
1057    fn copy_file(&mut self, sp: &Path, dp: &Path, scanned_meta: &Metadata) -> io::Result<()> {
1058        let ctx = |e: io::Error| wrap(Op::CopyFile, sp, Some(dp.to_path_buf()), e);
1059        self.files_seen += 1;
1060        if let Some(hook) = &mut self.file_hook {
1061            hook(self.files_seen, sp).map_err(ctx)?;
1062        }
1063        let src = open_source(sp).map_err(ctx)?;
1064        let meta = src.metadata().map_err(ctx)?;
1065        if !meta.is_file() || !same_file_identity(scanned_meta, &meta) {
1066            return Err(contract(
1067                Op::CopyFile,
1068                sp,
1069                Some(dp.to_path_buf()),
1070                io::ErrorKind::InvalidInput,
1071                "source entry changed identity after directory scan",
1072            ));
1073        }
1074        let written = if self.progress.is_none() {
1075            if !self.prepare_fast_dest(sp, dp)? {
1076                self.summary.skipped += 1;
1077                self.entry_done(dp);
1078                return Ok(());
1079            }
1080            self.copy_fast(sp, dp, src).map_err(ctx)?
1081        } else {
1082            let dst = match self.open_dest(sp, dp)? {
1083                Some(file) => file,
1084                None => {
1085                    self.summary.skipped += 1;
1086                    self.entry_done(dp);
1087                    return Ok(());
1088                }
1089            };
1090            self.copy_buffered(src, dst, &meta, dp).map_err(ctx)?
1091        };
1092        self.summary.bytes_copied = add_bytes(self.summary.bytes_copied, written);
1093        self.summary.files += 1;
1094        self.entry_done(dp);
1095        Ok(())
1096    }
1097
1098    /// Progress path: stream through the buffer from the no-follow handle
1099    /// into the claimed destination handle, one callback per chunk.
1100    fn copy_buffered(
1101        &mut self,
1102        mut src: File,
1103        mut dst: File,
1104        meta: &Metadata,
1105        dp: &Path,
1106    ) -> io::Result<u64> {
1107        let mut buf = std::mem::take(&mut self.buf);
1108        let mut written = 0u64;
1109        let result = loop {
1110            let n = match src.read(&mut buf) {
1111                Ok(n) => n,
1112                Err(e) => break Err(e),
1113            };
1114            if n == 0 {
1115                break Ok(());
1116            }
1117            if let Err(e) = dst.write_all(&buf[..n]) {
1118                break Err(e);
1119            }
1120            written = add_bytes(written, n as u64);
1121            if let Some(sink) = &mut self.progress {
1122                sink.bytes_copied = add_bytes(sink.bytes_copied, n as u64);
1123                sink.emit(dp);
1124            }
1125        };
1126        self.buf = buf;
1127        result?;
1128        dst.set_permissions(meta.permissions())?;
1129        if self.fsync {
1130            dst.sync_all()?;
1131        }
1132        Ok(written)
1133    }
1134
1135    /// Fast path: `std::fs::copy` creates the final file, then the source
1136    /// path is re-opened no-follow and compared against the handle held
1137    /// since the pre-copy check. Any failure removes the new file.
1138    fn copy_fast(&mut self, sp: &Path, dp: &Path, checked_src: File) -> io::Result<u64> {
1139        let result = fs::copy(sp, dp).and_then(|n| {
1140            confirm_copied_source(sp, &checked_src)?;
1141            if self.fsync {
1142                open_source(dp)?.sync_all()?;
1143            }
1144            Ok(n)
1145        });
1146        drop(checked_src);
1147        match result {
1148            Ok(written) => Ok(written),
1149            Err(copy_error) => match fs::remove_file(dp) {
1150                Ok(()) => Err(copy_error),
1151                Err(cleanup) if cleanup.kind() == io::ErrorKind::NotFound => Err(copy_error),
1152                Err(cleanup) => Err(wrap(Op::RemoveEntry, dp, None, cleanup)),
1153            },
1154        }
1155    }
1156}
1157
1158enum RootPrep {
1159    Proceed { created: bool },
1160    Noop,
1161}
1162
1163fn prepare_root(dst: &Path, overwrite: Overwrite, guard: &SourceGuard) -> io::Result<RootPrep> {
1164    match fs::create_dir(dst) {
1165        Ok(()) => Ok(RootPrep::Proceed { created: true }),
1166        Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {
1167            let meta = fs::symlink_metadata(dst).map_err(|e2| wrap(Op::Scan, dst, None, e2))?;
1168            if meta.is_dir() {
1169                guard.check(dst, &meta)?;
1170                Ok(RootPrep::Proceed { created: false })
1171            } else {
1172                match overwrite {
1173                    Overwrite::Error => Err(wrap(Op::CreateDir, dst, None, e)),
1174                    Overwrite::Skip => Ok(RootPrep::Noop),
1175                    Overwrite::Replace => {
1176                        guard.remove_dest_entry(dst)?;
1177                        fs::create_dir(dst).map_err(|e2| wrap(Op::CreateDir, dst, None, e2))?;
1178                        Ok(RootPrep::Proceed { created: true })
1179                    }
1180                }
1181            }
1182        }
1183        Err(e) if e.kind() == io::ErrorKind::NotFound => {
1184            let parent = dst.parent().unwrap_or(dst);
1185            Err(wrap(Op::CreateDir, parent, None, e))
1186        }
1187        Err(e) => Err(wrap(Op::CreateDir, dst, None, e)),
1188    }
1189}
1190
1191fn source_dir_meta(src: &Path) -> io::Result<Metadata> {
1192    let meta = fs::symlink_metadata(src).map_err(|e| wrap(Op::Scan, src, None, e))?;
1193    if !meta.is_dir() {
1194        return Err(contract(
1195            Op::Scan,
1196            src,
1197            None,
1198            io::ErrorKind::InvalidInput,
1199            "source is not a directory; tree operations take directories",
1200        ));
1201    }
1202    Ok(meta)
1203}
1204
1205/// Optimize the required single-file case without weakening merge behavior.
1206/// The destination root is claimed before the file copy, so its child slot is
1207/// private to this operation under the library's non-hostile caller model.
1208fn try_single_file_copy(
1209    src: &Path,
1210    dst: &Path,
1211    src_meta: &Metadata,
1212    known_dst: Option<&Metadata>,
1213) -> io::Result<Option<Summary>> {
1214    let mut entries = read_dir(src)?;
1215    let entry = match entries.next() {
1216        Some(entry) => entry.map_err(|e| wrap(Op::Scan, src, None, e))?,
1217        None => return Ok(None),
1218    };
1219    if entries.next().is_some() {
1220        return Ok(None);
1221    }
1222    let source_path = entry.path();
1223    let scanned = entry
1224        .metadata()
1225        .map_err(|e| wrap(Op::Scan, &source_path, None, e))?;
1226    if !scanned.is_file() {
1227        return Ok(None);
1228    }
1229    let checked = open_source(&source_path)
1230        .map_err(|e| wrap(Op::CopyFile, &source_path, Some(dst.to_path_buf()), e))?;
1231    let opened = checked
1232        .metadata()
1233        .map_err(|e| wrap(Op::CopyFile, &source_path, Some(dst.to_path_buf()), e))?;
1234    if !opened.is_file() || !same_file_identity(&scanned, &opened) {
1235        return Err(contract(
1236            Op::CopyFile,
1237            &source_path,
1238            Some(dst.to_path_buf()),
1239            io::ErrorKind::InvalidInput,
1240            "source entry changed identity after directory scan",
1241        ));
1242    }
1243    let created = match known_dst
1244        .cloned()
1245        .map(Ok)
1246        .unwrap_or_else(|| fs::symlink_metadata(dst))
1247    {
1248        Ok(meta) => {
1249            if !meta.is_dir() {
1250                return Ok(None);
1251            }
1252            let mut destination_entries = read_dir(dst)?;
1253            if destination_entries.next().is_some() {
1254                return Ok(None);
1255            }
1256            false
1257        }
1258        Err(e) if e.kind() == io::ErrorKind::NotFound => {
1259            fs::create_dir(dst).map_err(|e| wrap(Op::CreateDir, dst, None, e))?;
1260            true
1261        }
1262        Err(e) => return Err(wrap(Op::Scan, dst, None, e)),
1263    };
1264    let destination_path = dst.join(entry.file_name());
1265    let copied = fs::copy(&source_path, &destination_path).map_err(|e| {
1266        wrap(
1267            Op::CopyFile,
1268            &source_path,
1269            Some(destination_path.clone()),
1270            e,
1271        )
1272    })?;
1273    if let Err(e) = confirm_copied_source(&source_path, &checked) {
1274        return Err(match fs::remove_file(&destination_path) {
1275            Ok(()) => wrap(
1276                Op::CopyFile,
1277                &source_path,
1278                Some(destination_path.clone()),
1279                e,
1280            ),
1281            Err(cleanup) if cleanup.kind() == io::ErrorKind::NotFound => wrap(
1282                Op::CopyFile,
1283                &source_path,
1284                Some(destination_path.clone()),
1285                e,
1286            ),
1287            Err(cleanup) => wrap(Op::RemoveEntry, &destination_path, None, cleanup),
1288        });
1289    }
1290    drop(checked);
1291    if created {
1292        fs::set_permissions(dst, src_meta.permissions())
1293            .map_err(|e| wrap(Op::CreateDir, dst, None, e))?;
1294    }
1295    Ok(Some(Summary {
1296        bytes_copied: copied,
1297        files: 1,
1298        dirs: u64::from(created),
1299        symlinks: 0,
1300        skipped: 0,
1301    }))
1302}
1303
1304fn copy_tree_impl<'a>(
1305    src: &Path,
1306    dst: &Path,
1307    opts: &Options,
1308    mut progress_cb: Option<&'a mut dyn FnMut(&Progress<'_>)>,
1309    file_hook: Option<FileHook<'a>>,
1310) -> io::Result<Summary> {
1311    let src_meta = source_dir_meta(src)?;
1312    let known_dst = overlap_guard(src, &src_meta, dst)?;
1313    if progress_cb.is_none() && file_hook.is_none() {
1314        if let Some(summary) = try_single_file_copy(src, dst, &src_meta, known_dst.as_ref())? {
1315            return Ok(summary);
1316        }
1317    }
1318    let sink = match progress_cb.take() {
1319        Some(cb) => {
1320            let totals = scan_tree(src)?;
1321            let mut sink = ProgressSink::new(cb, &totals);
1322            sink.emit(dst);
1323            Some(sink)
1324        }
1325        None => None,
1326    };
1327    let mut guard = SourceGuard::new(src, &src_meta);
1328    guard.preflight_destination(dst)?;
1329    let root_created = match prepare_root(dst, opts.overwrite, &guard)? {
1330        RootPrep::Noop => return Ok(Summary::default()),
1331        RootPrep::Proceed { created } => created,
1332    };
1333    let buf = if sink.is_some() {
1334        vec![0; opts.buffer_size.max(1)]
1335    } else {
1336        Vec::new()
1337    };
1338    let mut engine = CopyEngine {
1339        overwrite: opts.overwrite,
1340        fsync: false,
1341        buf,
1342        summary: Summary::default(),
1343        progress: sink,
1344        file_hook,
1345        files_seen: 0,
1346        guard,
1347    };
1348    if root_created {
1349        engine.summary.dirs += 1;
1350    }
1351    engine.run(src, dst, root_created, src_meta.permissions())?;
1352    Ok(engine.summary)
1353}
1354
1355/// Test hooks for the staged move path.
1356pub(crate) struct MoveCtl<'a> {
1357    /// Skip the rename attempt so the staged path runs on one filesystem.
1358    pub(crate) force_staged: bool,
1359    /// Called before each regular file copy with the 1-based file ordinal.
1360    pub(crate) file_hook: Option<FileHook<'a>>,
1361    /// Called after finalize, before source removal.
1362    pub(crate) post_finalize: Option<VoidHook<'a>>,
1363    /// Called before the aside removal of a replaced destination. An error
1364    /// stands in for a failed removal.
1365    pub(crate) aside_removal: Option<PathHook<'a>>,
1366    /// Replaces destination-parent sync in tests. An error must roll final
1367    /// placement back before the function returns.
1368    pub(crate) parent_sync: Option<PathHook<'a>>,
1369}
1370
1371impl MoveCtl<'_> {
1372    fn none() -> Self {
1373        MoveCtl {
1374            force_staged: false,
1375            file_hook: None,
1376            post_finalize: None,
1377            aside_removal: None,
1378            parent_sync: None,
1379        }
1380    }
1381}
1382
1383/// What sits at `dst` before a move, from `symlink_metadata`.
1384#[derive(Clone, Copy)]
1385enum DstKind {
1386    Dir,
1387    Other,
1388}
1389
1390fn move_tree_impl<'a>(
1391    src: &Path,
1392    dst: &Path,
1393    opts: &Options,
1394    mut progress_cb: Option<&'a mut dyn FnMut(&Progress<'_>)>,
1395    ctl: MoveCtl<'a>,
1396) -> io::Result<Summary> {
1397    let src_meta = source_dir_meta(src)?;
1398    overlap_guard(src, &src_meta, dst)?;
1399    let existing = match fs::symlink_metadata(dst) {
1400        Ok(meta) if meta.is_dir() => Some(DstKind::Dir),
1401        Ok(_) => Some(DstKind::Other),
1402        Err(e) if e.kind() == io::ErrorKind::NotFound => None,
1403        Err(e) => return Err(wrap(Op::Scan, dst, None, e)),
1404    };
1405    // The pre-scan runs only when the caller asked for totals. The
1406    // non-progress path issues the rename before reading the source.
1407    let (mut sink, totals) = match progress_cb.take() {
1408        Some(cb) => {
1409            let totals = scan_tree(src)?;
1410            let mut sink = ProgressSink::new(cb, &totals);
1411            sink.emit(dst);
1412            (Some(sink), Some(totals))
1413        }
1414        None => (None, None),
1415    };
1416    let replace = match (existing, opts.overwrite) {
1417        (None, _) => None,
1418        (Some(_), Overwrite::Error) => {
1419            return Err(contract(
1420                Op::Finalize,
1421                dst,
1422                Some(src.to_path_buf()),
1423                io::ErrorKind::AlreadyExists,
1424                "destination already exists",
1425            ));
1426        }
1427        (Some(_), Overwrite::Skip) => return Ok(Summary::default()),
1428        (Some(kind), Overwrite::Replace) => Some(kind),
1429    };
1430    if replace.is_none() && !ctl.force_staged {
1431        match fs::rename(src, dst) {
1432            Ok(()) => {
1433                let summary = match &totals {
1434                    Some(totals) => totals.summary(),
1435                    None => summarize_moved(dst),
1436                };
1437                if let Some(sink) = &mut sink {
1438                    sink.bytes_copied = summary.bytes_copied;
1439                    sink.entries_done = sink.entries_total;
1440                    sink.emit(dst);
1441                }
1442                return Ok(summary);
1443            }
1444            Err(e) if e.raw_os_error() == Some(CROSS_DEVICE_RAW) => {
1445                // Cross-device: fall through to the staged path.
1446            }
1447            Err(e) => return Err(wrap(Op::Rename, src, Some(dst.to_path_buf()), e)),
1448        }
1449    }
1450    staged_move(src, dst, opts, &src_meta, sink, replace, ctl)
1451}
1452
1453#[cfg(unix)]
1454fn make_created_tree_removable(path: &Path) -> io::Result<()> {
1455    use std::os::unix::fs::PermissionsExt;
1456
1457    let mut stack = vec![path.to_path_buf()];
1458    while let Some(dir) = stack.pop() {
1459        let meta = match fs::symlink_metadata(&dir) {
1460            Ok(meta) => meta,
1461            Err(e) if e.kind() == io::ErrorKind::NotFound => continue,
1462            Err(e) => return Err(e),
1463        };
1464        if !meta.is_dir() {
1465            continue;
1466        }
1467        let mode = meta.permissions().mode();
1468        fs::set_permissions(&dir, fs::Permissions::from_mode(mode | 0o700))?;
1469        for entry in fs::read_dir(&dir)? {
1470            let entry = entry?;
1471            if fs::symlink_metadata(entry.path())?.is_dir() {
1472                stack.push(entry.path());
1473            }
1474        }
1475    }
1476    Ok(())
1477}
1478
1479#[cfg(not(unix))]
1480fn make_created_tree_removable(_path: &Path) -> io::Result<()> {
1481    Ok(())
1482}
1483
1484fn cleanup_created_dir(path: &Path) -> io::Result<()> {
1485    match fs::remove_dir_all(path) {
1486        Ok(()) => Ok(()),
1487        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(()),
1488        Err(_) => {
1489            make_created_tree_removable(path).map_err(|e| wrap(Op::RemoveEntry, path, None, e))?;
1490            fs::remove_dir_all(path).map_err(|e| wrap(Op::RemoveEntry, path, None, e))
1491        }
1492    }
1493}
1494
1495fn restore_parent(parent: &Path, permissions: &fs::Permissions) -> io::Result<()> {
1496    fs::set_permissions(parent, permissions.clone())
1497        .map_err(|e| wrap(Op::Finalize, parent, None, e))
1498}
1499
1500fn sync_move_parent(ctl: &mut MoveCtl<'_>, parent: &Path) -> io::Result<()> {
1501    match ctl.parent_sync.as_mut() {
1502        Some(hook) => hook(parent),
1503        None => fsync_dir(parent),
1504    }
1505}
1506
1507fn rollback_replacement(
1508    parent: &Path,
1509    parent_perms: &fs::Permissions,
1510    dst: &Path,
1511    aside: &Path,
1512    staging: &Path,
1513) -> io::Result<()> {
1514    restore_parent(parent, parent_perms)?;
1515    fs::rename(dst, staging)
1516        .map_err(|e| wrap(Op::Finalize, dst, Some(staging.to_path_buf()), e))?;
1517    fs::rename(aside, dst).map_err(|e| wrap(Op::Finalize, aside, Some(dst.to_path_buf()), e))?;
1518    cleanup_created_dir(staging)?;
1519    fsync_dir(parent).map_err(|e| wrap(Op::Finalize, parent, None, e))
1520}
1521
1522fn rollback_new_destination(
1523    parent: &Path,
1524    parent_perms: &fs::Permissions,
1525    dst: &Path,
1526    staging: &Path,
1527) -> io::Result<()> {
1528    restore_parent(parent, parent_perms)?;
1529    fs::rename(dst, staging)
1530        .map_err(|e| wrap(Op::Finalize, dst, Some(staging.to_path_buf()), e))?;
1531    cleanup_created_dir(staging)?;
1532    fsync_dir(parent).map_err(|e| wrap(Op::Finalize, parent, None, e))
1533}
1534
1535fn staged_move<'a>(
1536    src: &Path,
1537    dst: &Path,
1538    opts: &Options,
1539    src_meta: &Metadata,
1540    progress: Option<ProgressSink<'a>>,
1541    replace: Option<DstKind>,
1542    mut ctl: MoveCtl<'a>,
1543) -> io::Result<Summary> {
1544    let parent = match dst.parent() {
1545        Some(p) if !p.as_os_str().is_empty() => p.to_path_buf(),
1546        Some(_) => PathBuf::from("."),
1547        None => {
1548            return Err(contract(
1549                Op::Finalize,
1550                dst,
1551                None,
1552                io::ErrorKind::InvalidInput,
1553                "destination has no parent directory",
1554            ));
1555        }
1556    };
1557    dst.file_name().ok_or_else(|| {
1558        contract(
1559            Op::Finalize,
1560            dst,
1561            None,
1562            io::ErrorKind::InvalidInput,
1563            "destination has no file name",
1564        )
1565    })?;
1566    let parent_perms = fs::symlink_metadata(&parent)
1567        .map_err(|e| wrap(Op::Scan, &parent, None, e))?
1568        .permissions();
1569    let mut guard = SourceGuard::new(src, src_meta);
1570    guard.preflight_destination(dst)?;
1571    let tag = call_tag();
1572    let staging = parent.join(hidden_sibling_name(&tag, "part"));
1573    fs::create_dir(&staging).map_err(|e| wrap(Op::CreateDir, &staging, None, e))?;
1574    let buf = if progress.is_some() {
1575        vec![0; opts.buffer_size.max(1)]
1576    } else {
1577        Vec::new()
1578    };
1579    let mut engine = CopyEngine {
1580        overwrite: Overwrite::Error,
1581        fsync: true,
1582        buf,
1583        summary: Summary {
1584            dirs: 1,
1585            ..Summary::default()
1586        },
1587        progress,
1588        file_hook: ctl.file_hook.take(),
1589        files_seen: 0,
1590        guard,
1591    };
1592    if let Err(e) = engine.run(src, &staging, true, src_meta.permissions()) {
1593        drop(engine);
1594        cleanup_created_dir(&staging)?;
1595        return Err(e);
1596    }
1597    let summary = engine.summary.clone();
1598    drop(engine);
1599    match replace {
1600        Some(kind) => {
1601            let aside = parent.join(hidden_sibling_name(&tag, "old"));
1602            if let Err(e) = fs::rename(dst, &aside) {
1603                cleanup_created_dir(&staging)?;
1604                return Err(wrap(Op::Finalize, dst, Some(aside), e));
1605            }
1606            if let Err(e) = fs::rename(&staging, dst) {
1607                restore_parent(&parent, &parent_perms)?;
1608                fs::rename(&aside, dst).map_err(|restore| {
1609                    wrap(Op::Finalize, &aside, Some(dst.to_path_buf()), restore)
1610                })?;
1611                cleanup_created_dir(&staging)?;
1612                fsync_dir(&parent).map_err(|sync| wrap(Op::Finalize, &parent, None, sync))?;
1613                return Err(wrap(Op::Finalize, &staging, Some(dst.to_path_buf()), e));
1614            }
1615            if let Err(e) = sync_move_parent(&mut ctl, &parent) {
1616                rollback_replacement(&parent, &parent_perms, dst, &aside, &staging)?;
1617                return Err(wrap(Op::Finalize, &parent, Some(dst.to_path_buf()), e));
1618            }
1619            let removed = match ctl.aside_removal.as_mut() {
1620                Some(hook) => hook(&aside),
1621                None => Ok(()),
1622            }
1623            .and_then(|()| match kind {
1624                DstKind::Dir => fs::remove_dir_all(&aside),
1625                DstKind::Other => fs::remove_file(&aside),
1626            });
1627            if let Err(e) = removed {
1628                rollback_replacement(&parent, &parent_perms, dst, &aside, &staging)?;
1629                return Err(wrap(Op::RemoveEntry, &aside, Some(dst.to_path_buf()), e));
1630            }
1631        }
1632        None => {
1633            if let Err(e) = fs::rename(&staging, dst) {
1634                cleanup_created_dir(&staging)?;
1635                return Err(wrap(Op::Finalize, &staging, Some(dst.to_path_buf()), e));
1636            }
1637            if let Err(e) = sync_move_parent(&mut ctl, &parent) {
1638                rollback_new_destination(&parent, &parent_perms, dst, &staging)?;
1639                return Err(wrap(Op::Finalize, &parent, Some(dst.to_path_buf()), e));
1640            }
1641        }
1642    }
1643    if let Some(hook) = ctl.post_finalize.as_mut() {
1644        hook();
1645    }
1646    remove_tree(src).map_err(|e| wrap(Op::RemoveSource, src, None, e))?;
1647    Ok(summary)
1648}
1649
1650fn validate_options(opts: &Options) -> io::Result<()> {
1651    if opts.buffer_size > isize::MAX as usize {
1652        return Err(io::Error::new(
1653            io::ErrorKind::InvalidInput,
1654            "buffer_size exceeds maximum allocation",
1655        ));
1656    }
1657    Ok(())
1658}
1659
1660/// Recursively copy the directory tree at `src` to `dst`.
1661///
1662/// `dst` names the resulting root (`src/<rel>` maps to `dst/<rel>`). Regular
1663/// files are copied byte-for-byte through `std::fs::copy`, empty directories
1664/// are created, symlinks are reproduced verbatim and treated as leaves, and
1665/// Unix permission bits are preserved on files and directories. Overlapping
1666/// roots are rejected with `InvalidInput` before anything is touched. On
1667/// error, `src` stays unchanged, and partial destination output may
1668/// remain.
1669pub fn copy_tree(
1670    src: impl AsRef<Path>,
1671    dst: impl AsRef<Path>,
1672    opts: &Options,
1673) -> io::Result<Summary> {
1674    validate_options(opts)?;
1675    copy_tree_impl(src.as_ref(), dst.as_ref(), opts, None, None)
1676}
1677
1678/// [`copy_tree`] with a progress callback.
1679///
1680/// Files stream through a buffer of [`Options::buffer_size`] bytes. The
1681/// callback runs once after the pre-scan, at most once per copied chunk,
1682/// and at least once at each entry's completion, zero-byte files included.
1683/// `bytes_copied` is non-decreasing, and totals are fixed by one pre-scan.
1684/// Callback panics propagate to the caller.
1685pub fn copy_tree_with_progress(
1686    src: impl AsRef<Path>,
1687    dst: impl AsRef<Path>,
1688    opts: &Options,
1689    mut on_progress: impl FnMut(&Progress<'_>),
1690) -> io::Result<Summary> {
1691    validate_options(opts)?;
1692    copy_tree_impl(
1693        src.as_ref(),
1694        dst.as_ref(),
1695        opts,
1696        Some(&mut on_progress),
1697        None,
1698    )
1699}
1700
1701/// Move the directory tree at `src` to `dst` without ever endangering `src`.
1702///
1703/// Phases: a rename attempt when `dst` is absent, issued before any read of
1704/// `src`, so every entry type the filesystem holds moves with it. When the
1705/// rename fails across devices, or when an existing `dst` is being
1706/// replaced, a staged copy runs into a hidden sibling of `dst` (files
1707/// fsynced, directories fsynced on Unix), then a finalize rename, and only
1708/// then removal of `src`. A failure before source removal returns the error
1709/// with `src` unchanged, `dst` as it was, and no hidden sibling left under
1710/// the parent of `dst`. A failure during source removal reports
1711/// [`Op::RemoveSource`], and `dst` is already complete, so the call can be
1712/// retried.
1713///
1714/// An existing `dst` is handled as a whole: [`Overwrite::Error`] returns
1715/// `AlreadyExists`, [`Overwrite::Skip`] returns a zero summary with `src`
1716/// left in place, and [`Overwrite::Replace`] swaps the finished tree in and
1717/// then removes the old entry with the primitive for its type (a file or
1718/// link with `remove_file`, a directory with `remove_dir_all`), so the final
1719/// path always has either the old entry or a complete replacement available.
1720///
1721/// After a successful rename the summary is taken from a scan of `dst`. A
1722/// directory that scan cannot read counts as one directory and its contents
1723/// are left out.
1724pub fn move_tree(
1725    src: impl AsRef<Path>,
1726    dst: impl AsRef<Path>,
1727    opts: &Options,
1728) -> io::Result<Summary> {
1729    validate_options(opts)?;
1730    move_tree_impl(src.as_ref(), dst.as_ref(), opts, None, MoveCtl::none())
1731}
1732
1733/// [`move_tree`] with a progress callback.
1734///
1735/// See [`copy_tree_with_progress`] for the callback contract. Totals need a
1736/// pre-scan of `src`, so this variant reads the source before the rename
1737/// attempt. When the rename fast path applies, the callback runs once after
1738/// the rename with `bytes_copied` equal to the pre-scanned byte size.
1739pub fn move_tree_with_progress(
1740    src: impl AsRef<Path>,
1741    dst: impl AsRef<Path>,
1742    opts: &Options,
1743    mut on_progress: impl FnMut(&Progress<'_>),
1744) -> io::Result<Summary> {
1745    validate_options(opts)?;
1746    move_tree_impl(
1747        src.as_ref(),
1748        dst.as_ref(),
1749        opts,
1750        Some(&mut on_progress),
1751        MoveCtl::none(),
1752    )
1753}
1754
1755/// Recursively remove the tree at `path`.
1756///
1757/// Decisions come from `symlink_metadata` alone: if `path` is a symlink,
1758/// only the link is removed, and symlinks inside the tree are removed as
1759/// links, so a linked-in tree survives. A missing `path` is `NotFound`,
1760/// which includes reporting a broken symlink's removal honestly instead of
1761/// silently skipping it. Removal is not transactional: entries already
1762/// removed stay removed when a later entry fails.
1763pub fn remove_tree(path: impl AsRef<Path>) -> io::Result<()> {
1764    let path = path.as_ref();
1765    let meta = fs::symlink_metadata(path).map_err(|e| wrap(Op::Scan, path, None, e))?;
1766    if !meta.is_dir() {
1767        return fs::remove_file(path).map_err(|e| wrap(Op::RemoveEntry, path, None, e));
1768    }
1769    let mut frames: Vec<(PathBuf, fs::ReadDir)> = vec![(path.to_path_buf(), read_dir(path)?)];
1770    while let Some(top) = frames.last_mut() {
1771        let next = top.1.next();
1772        match next {
1773            Some(entry) => {
1774                let dir = frames.last().expect("frame stack non-empty").0.clone();
1775                let entry = entry.map_err(|e| wrap(Op::Scan, &dir, None, e))?;
1776                let p = entry.path();
1777                let meta = fs::symlink_metadata(&p).map_err(|e| wrap(Op::Scan, &p, None, e))?;
1778                if meta.is_dir() {
1779                    let entries = read_dir(&p)?;
1780                    frames.push((p, entries));
1781                } else {
1782                    fs::remove_file(&p).map_err(|e| wrap(Op::RemoveEntry, &p, None, e))?;
1783                }
1784            }
1785            None => {
1786                let (dir, _) = frames.pop().expect("frame stack non-empty");
1787                fs::remove_dir(&dir).map_err(|e| wrap(Op::RemoveEntry, &dir, None, e))?;
1788            }
1789        }
1790    }
1791    Ok(())
1792}
1793
1794/// Total size in bytes of the tree at `path`.
1795///
1796/// Sums regular-file byte lengths plus symlink target lengths (from
1797/// `symlink_metadata`). Directories contribute zero and links are leaves, so
1798/// a link into a large tree costs its link length and link cycles cannot
1799/// recurse. Values are byte lengths, not disk blocks, so they
1800/// differ from `du`.
1801pub fn tree_size(path: impl AsRef<Path>) -> io::Result<u64> {
1802    let path = path.as_ref();
1803    let meta = fs::symlink_metadata(path).map_err(|e| wrap(Op::Scan, path, None, e))?;
1804    if !meta.is_dir() {
1805        return Ok(meta.len());
1806    }
1807    let mut total = 0u64;
1808    let mut stack = vec![path.to_path_buf()];
1809    while let Some(dir) = stack.pop() {
1810        let rd = fs::read_dir(&dir).map_err(|e| wrap(Op::Scan, &dir, None, e))?;
1811        for entry in rd {
1812            let entry = entry.map_err(|e| wrap(Op::Scan, &dir, None, e))?;
1813            let meta = fs::symlink_metadata(entry.path())
1814                .map_err(|e| wrap(Op::Scan, &entry.path(), None, e))?;
1815            if meta.file_type().is_dir() {
1816                stack.push(entry.path());
1817            } else {
1818                total = add_bytes(total, meta.len());
1819            }
1820        }
1821    }
1822    Ok(total)
1823}