Expand description
cp2 — a pure-Rust, high-performance cp and rsync-style copy/sync tool
for local directories or over the network (Linux, macOS, Windows).
cp2 syncs a directory tree between two machines like rsync, but with a
modern delta engine: content-defined chunking (FastCDC) plus BLAKE3, so an
update retransmits only the chunks an edit actually touched — not the tail
of the file. It rides the system ssh client (the remote end runs
cp2 --server; sshd does authentication and permission enforcement, so
cp2 contains zero auth code), and the client auto-deploys a matching
binary to a fresh server on first use.
§Library usage
The sync engine runs over any byte stream — the CLI wires it to an
ssh channel, but a pipe, a socket, or a future mobile connection works
the same way:
use cp2::{Executor, ExecutorOptions};
use tokio::io::{AsyncRead, AsyncWrite};
async fn push_to_peer() -> cp2::Result<()> {
// Any byte stream with a `cp2 --server` on the other end.
let send: Box<dyn AsyncWrite + Unpin + Send> = Box::new(tokio::io::sink());
let recv: Box<dyn AsyncRead + Unpin + Send> = Box::new(tokio::io::empty());
let mut executor = Executor::new(send, recv);
executor
.push(std::path::Path::new("photos/"), &ExecutorOptions::default())
.await?;
Ok(())
}Executor drives push (push), pull (pull), multi-root glob pushes
(push_multi), and the sshd-invoked server role (serve). Location
parses user@host:path targets; ExecutorOptions carries the rsync
decision flags (--delete, --checksum, --archive, …).
§What you get
- Delta updates — changed chunks only, via
FastCDCcontent-defined chunking andBLAKE3(seedelta). - Verification & move-off —
--verifyproves the destination bytes match the source (on-the-fly hashing, no re-reads);--remove-source-filesdeletes the source only after the destination is hash-verified, fsynced, and re-checked — made for freeing an instrument’s disk. - rsync semantics —
-a(special files/devices on Unix; owner/group are never preserved — 0-Root),--delete,--backup,--no-*opt-outs, include/exclude globs, exit code 23. - Realtime watch (
-W) — event-driven push, server-driven pull. - Cross-platform — Linux, macOS, Windows, in any combination; the engine is embeddable (runs over any byte stream).
§Architecture
Decision logic is pure; async I/O is orchestrated by the executor:
scanner → Manifest → planner → SyncPlan → strategy → executor → verifysync::scannerwalks a tree into a serializableManifestsync::plannermaps source × destination manifests to aSyncPlansync::strategypicks the transfer tier per file (batch/whole/delta/chunked)- [
sync::sender] / [sync::receiver] play the two protocol roles protocolis the wire format, agnostic of the transportplatformis the portable filesystem layer (staging, metadata)
§Security model
Authentication and access control are entirely sshd’s: the remote
cp2 --server runs as your account, and the receiver sanitizes every
peer-supplied path against directory traversal and symlink escapes.
§Acknowledgments
cp2’s design and parts of its code are informed by copia, sparsync, sy, robosync, pxs, and the rsync ecosystem (rsync, librsync, rusync, zsync-rs, ripsync, msy, syncz). They are adapted (MIT/BSD-licensed, compatible with cp2’s MIT license) and credited per module in the source headers. See the README’s Acknowledgments table for the full map.
Re-exports§
pub use error::Error;pub use error::Result;pub use sync::BandwidthLimiter;pub use sync::Executor;pub use sync::ExecutorOptions;pub use sync::FileEntry;pub use sync::FilterSet;pub use sync::Manifest;pub use sync::Planner;pub use sync::PlannerConfig;pub use sync::ScanOptions;pub use sync::Scanner;pub use sync::SyncAction;pub use sync::SyncPlan;pub use sync::SyncStats;pub use sync::SyncTask;pub use target::Location;pub use target::RemoteTarget;pub use transport::JumpHost;pub use transport::RemoteClient;pub use transport::Session;pub use transport::SessionHandle;pub use transport::Transport;pub use transport::spawn_ssh;
Modules§
- cli
- commands
- delta
- Delta computation: content-defined-chunk (
FastCDC) delta. - error
- High-level error type aggregating all crate errors.
- platform
- Platform abstraction layer.
- protocol
- The cp2 peer wire protocol: message types (
Frame) and the length-prefixed, optionally-compressed codec (stream). - security
- Security utilities, including path sanitization.
- sync
- Synchronization orchestration: pipeline of scanner → planner → strategy → executor, over a single byte stream (the ssh stdio channel).
- target
- Sync targets: local paths and remote
user@host:port/pathlocations. - transport
- Transport layer.