file-engine 2.0.0

Async, cross-platform file operations engine for desktop apps and developer tools: copy, move, sync, watch, and compress files with progress reporting and cancellation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

use std::path::PathBuf;
use std::time::Instant;

use tokio_util::sync::CancellationToken;

use crate::error::Result;
use crate::handle::Handle;
use crate::planner::{BatchConfig, ErrorStrategy, OperationOutcome, SortOrder};
use crate::profiler::DEFAULT_SMALL_FILE_THRESHOLD;
use crate::progress::ProgressReporter;

use super::default_concurrency;
use super::pipeline::run_copy_pipeline;

pub struct CopyBuilder {
    source: PathBuf,
    dest: PathBuf,
    overwrite: bool,
    /// Unconditional field even though only `.preserve_permissions()`
    /// (Unix-only) can ever set it.
    preserve_permissions: bool,
    allow_filesystem_integrity_risk: bool,
    small_file_threshold: Option<u64>,
    batch_config: BatchConfig,
    concurrency: Option<usize>,
}

impl CopyBuilder {
    pub(crate) fn new(source: impl Into<PathBuf>, dest: impl Into<PathBuf>) -> Self {
        Self {
            source: source.into(),
            dest: dest.into(),
            overwrite: false,
            preserve_permissions: false,
            allow_filesystem_integrity_risk: false,
            small_file_threshold: None,
            batch_config: BatchConfig::default(),
            concurrency: None,
        }
    }

    pub fn overwrite(mut self, overwrite: bool) -> Self {
        self.overwrite = overwrite;
        self
    }

    #[cfg(all(unix, feature = "permissions"))]
    pub fn preserve_permissions(mut self, preserve: bool) -> Self {
        self.preserve_permissions = preserve;
        self
    }

    /// Proceed even when the destination filesystem has a known
    /// write-integrity risk on this platform (currently: exFAT on
    /// macOS) — without this, `.start()`'s `Handle` resolves to
    /// `Err(Error::FilesystemIntegrityRisk)` before any data is written.
    /// See `docs/guide/filesystem-safety.md`.
    pub fn allow_filesystem_integrity_risk(mut self, allow: bool) -> Self {
        self.allow_filesystem_integrity_risk = allow;
        self
    }

    pub fn small_file_threshold(mut self, bytes: u64) -> Self {
        self.small_file_threshold = Some(bytes);
        self
    }

    pub fn max_bytes_per_batch(mut self, bytes: u64) -> Self {
        self.batch_config.max_bytes_per_batch = bytes;
        self
    }

    pub fn max_files_per_batch(mut self, n: usize) -> Self {
        self.batch_config.max_files_per_batch = Some(n);
        self
    }

    pub fn batch_sort_order(mut self, order: SortOrder) -> Self {
        self.batch_config.sort_order = order;
        self
    }

    pub fn on_error(mut self, strategy: ErrorStrategy) -> Self {
        self.batch_config.error_strategy = strategy;
        self
    }

    pub fn batch_concurrency(mut self, n: usize) -> Self {
        self.concurrency = Some(n);
        self
    }

    pub fn start(self) -> Result<Handle<OperationOutcome>> {
        let cancel = CancellationToken::new();
        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
        let reporter = ProgressReporter::new(tx);

        let concurrency = self.concurrency.unwrap_or_else(default_concurrency);
        let threshold = self
            .small_file_threshold
            .unwrap_or(DEFAULT_SMALL_FILE_THRESHOLD);
        let cancel_for_task = cancel.clone();

        let join_handle = tokio::spawn(async move {
            let started = Instant::now();
            let mut outcome = run_copy_pipeline(
                &self.source,
                &self.dest,
                self.overwrite,
                self.preserve_permissions,
                self.allow_filesystem_integrity_risk,
                threshold,
                &self.batch_config,
                concurrency,
                cancel_for_task,
                reporter,
            )
            .await?;
            outcome.duration = started.elapsed();
            Ok(outcome)
        });

        Ok(Handle::new(join_handle, rx, cancel))
    }
}