Crate gravityfile_ops

Expand description

§gravityfile-ops

File operations for gravityfile: copy, move, rename, create, delete, undo and archives.

This crate exists for the grav binary and its sibling crates. Its API follows their needs and can change in any minor release.

Long-running operations run on blocking threads and report through a channel: best-effort OperationProgress snapshots, interactive ConflictRequests, and one reliable completion message. Dropping the receiver cancels the operation.

§Safety model

New content is assembled in a private staging directory beside its destination and published with a single no-clobber rename, so a failed or cancelled operation never leaves a partial item at a visible path and never silently replaces anything.
Overwrites the user approves move the replaced item to the system Trash (or delete it permanently, if configured) only after the replacement is complete.
Copies skip entries they cannot read and report each one instead of discarding everything that did copy; cross-filesystem moves keep the source unless every entry arrived.
Completed operations return what an undo needs as an UndoEntry. execute_undo moves and renames items back, sends copies to the Trash, and removes created files and directories only while they are still empty.

use gravityfile_ops::{CancellationToken, TransferOptions, TransferResult, start_copy};

let dir = tempfile::tempdir()?;
let source = dir.path().join("notes.txt");
let backup = dir.path().join("backup");
std::fs::write(&source, "hello")?;
std::fs::create_dir(&backup)?;

let runtime = tokio::runtime::Runtime::new()?;
let complete = runtime.block_on(async {
    let mut events = start_copy(
        vec![source],
        backup.clone(),
        TransferOptions::default(),
        CancellationToken::new(),
    );
    while let Some(event) = events.recv().await {
        match event {
            TransferResult::Progress(_) => {}
            // Dropping a request skips that item.
            TransferResult::Conflict(_) => {}
            TransferResult::Complete(complete) => return Some(complete),
        }
    }
    None
});

let complete = complete.expect("copy completes");
assert_eq!(complete.inner.succeeded, 1);
assert_eq!(std::fs::read_to_string(backup.join("notes.txt"))?, "hello");

§Licence

MIT or Apache-2.0, at your option.

Re-exports§

pub use archive::ArchiveError;
pub use archive::ArchiveFormat;
pub use archive::ArchiveResult;
pub use archive::ExtractLimits;
pub use archive::create_archive;
pub use archive::create_archive_cancellable;
pub use archive::extract_archive;
pub use archive::extract_archive_cancellable;
pub use archive::extract_archive_with;

Modules§

archive: Archive extraction and creation.

Structs§

CancellationToken: A token which can be used to signal a cancellation request to one or more tasks.
Conflict: A conflict detected during a file operation.
ConflictRequest: A conflict awaiting an answer from the caller.
DeleteComplete: Completion of a delete.
OperationComplete: Result of a completed operation.
OperationError: A problem with one path during an operation.
OperationProgress: Progress information for an ongoing operation.
TransferComplete: Completion of a copy or move.
TransferOptions: Options for copy and move.
UndoComplete: Completion of an undo.
UndoEntry: A recorded operation.
UndoLog: Bounded, most-recent-last undo history.

Enums§

ConflictKind: The kind of conflict encountered.
ConflictResolution: How to resolve a conflict.
CreateResult: Result sent through the channel during create operations.
DeleteMode: Where deleted items go.
DeleteResult: Message sent while a delete runs.
OperationType: The type of operation being performed.
RenameResult: Message sent while a rename runs.
ReplacePolicy: How an existing destination is disposed of when the user chooses to overwrite it.
TransferResult: Message sent while a copy or move runs.
UndoResult: Message sent while an undo runs.
UndoableOperation: An operation that can be reversed.

Constants§

OPERATION_CHANNEL_SIZE: Channel capacity for operation messages.
STAGING_PREFIX: Prefix of every staging directory this crate creates.

Functions§

auto_rename_path: Generate an auto-renamed path to avoid conflicts.
execute_undo: Reverse entry. Items are processed independently; failures are reported and returned in UndoComplete::remaining.
rename_paths: Rename a set of paths as one unit, including swaps (a→b, b→a), cycles and case-only changes on case-insensitive filesystems.
start_copy: Copy sources into the destination directory.
start_create_directory: Start directory creation with the same delivery semantics as file creation.
start_create_file: Start file creation. Dropping the receiver prevents queued work from starting; active filesystem calls are awaited and cannot be interrupted.
start_delete: Delete items, each given as (path, size); the size feeds progress. Symlinks are removed themselves, never their targets.
start_move: Move sources into the destination directory. Same-filesystem moves are a single rename; cross-filesystem moves copy, then delete the source only when every entry arrived.
start_rename: Rename source to new_name within its directory.
validate_filename: Validate a new file name against portable rules.