Crate common 

Common utilities and types for RCP file operation tools

This crate provides shared functionality used across all RCP tools (rcp, rrm, rlink, rcmp). It includes core operations (copy, remove, link, compare), progress reporting, metadata preservation, and runtime configuration.

Core Modules

• copy - File copying operations with metadata preservation and error handling
• rm - File removal operations
• link - Hard-linking operations
• cmp - File comparison operations (metadata-based)
• preserve - Metadata preservation settings and operations
• progress - Progress tracking and reporting
• filecmp - File metadata comparison utilities
• remote_tracing - Remote tracing support for distributed operations

Key Types

RcpdType

Identifies the role of a remote copy daemon:

• Source - reads files from source host
• Destination - writes files to destination host

ProgressType

Controls progress reporting display:

• Auto - automatically choose based on terminal type
• ProgressBar - animated progress bar (for interactive terminals)
• TextUpdates - periodic text updates (for logging/non-interactive)

Progress Reporting

The crate provides a global progress tracking system accessible via get_progress(). Progress can be displayed in different formats depending on the execution context.

Progress output goes to stderr, while logs go to stdout, allowing users to redirect logs to a file while still viewing interactive progress.

Runtime Configuration

The run function provides a unified entry point for all RCP tools with support for:

• Progress tracking and reporting
• Logging configuration (quiet/verbose modes)
• Resource limits (max workers, open files, throttling)
• Tokio runtime setup
• Remote tracing integration

Examples

Basic Copy Operation

use std::path::Path;
let src = Path::new("/source");
let dst = Path::new("/destination");

let settings = common::copy::Settings {
    dereference: false,
    fail_early: false,
    overwrite: false,
    overwrite_compare: Default::default(),
    overwrite_filter: None,
    ignore_existing: false,
    chunk_size: 0,
    skip_specials: false,
    remote_copy_buffer_size: 0,
    filter: None,
    dry_run: None,
};
let preserve = common::preserve::preserve_none();

let summary = common::copy(src, dst, &settings, &preserve).await?;
println!("Copied {} files", summary.files_copied);

Metadata Comparison

use std::path::Path;
let src = Path::new("/path1");
let dst = Path::new("/path2");

// output differences to stdout (use false for quiet mode)
let log = common::cmp::LogWriter::new(None, true, common::cmp::OutputFormat::default()).await?;
let settings = common::cmp::Settings {
    fail_early: false,
    exit_early: false,
    expand_missing: false,
    compare: Default::default(),
    filter: None,
};

let summary = common::cmp(src, dst, &log, &settings).await?;
println!("Comparison complete: {}", summary);

Re-exports

pub use config::AutoMetaThrottleConfig;

pub use config::DryRunMode;

pub use config::DryRunWarnings;

pub use config::OutputConfig;

pub use config::RuntimeConfig;

pub use config::ThrottleConfig;

pub use config::TracingConfig;

pub use progress::RcpdProgressPrinter;

pub use progress::SerializableProgress;

Modules

cli

Common CLI arguments shared by every RCP binary.

cmp

config

Configuration types for runtime and execution settings

copy

dry_run

Dry-run reporting helpers shared by copy, link, and rm operations.

error

Generic error type for tree-walking operations that preserves the partial summary (work that completed before the error) alongside the error chain.

error_collector

Collects and deduplicates errors for non-fail-early operation modes.

filecmp

filegen

filter

Pattern-based file filtering for include/exclude operations

histogram_logger

Process-wide histogram logger task.

histogram_panel

Pure rendering of per-(side, op) latency distribution panels.

link

observability

Process-wide registry of congestion-control snapshot streams.

preserve

progress

remote_tracing

rm

version

walk

Shared primitives for directory-walking operations (copy, link, rm).

Structs

ProgressSettings

RemoteRuntimeStats

runtime stats collected from remote rcpd processes for display at the end of a remote copy

RuntimeStats

runtime statistics collected from a process (CPU time, memory usage)

Enums

GeneralProgressType

MetadataOp

Which metadata syscall is being measured.

ProgressType

RcpdType

Side

Which side of an operation a probe is on.

Functions

cmp

collect_runtime_stats

collects runtime statistics (CPU time, memory) for the current process

copy

generate_debug_log_filename

generate_trace_filename

Generate a trace filename with identifier, hostname, PID, and timestamp.

get_progress

is_localhost

checks if a host string refers to the local machine. returns true for localhost, 127.0.0.1, ::1, [::1], or the actual hostname

link

parse_compare_settings

parse_metadata_cmp_settings

parse_preserve_settings

rm

run

set_remote_runtime_stats

stores remote runtime stats for display at the end of a remote copy operation

validate_update_compare_vs_preserve

Validates that every attribute checked by –update’s comparison is actually being preserved. Skips size (always preserved via content copy) and ctime (kernel-managed, cannot be set).

Type Aliases

ProgressSnapshot