Skip to content

Architecture

Andrew Paolucci edited this page Nov 19, 2026 · 1 revision

Workspace Architecture

robocopy2rust is structured as a modular 7-crate Cargo workspace (edition = "2024", resolver 2). UI layers are strictly decoupled from core domain logic, process execution, reporting, CLI, and MCP automation.


Crate Dependency Architecture

flowchart LR
    CORE["robocopy2rust-core<br/>Model, Quoting, Parsers, Validator,<br/>Exit Codes, Presets, Profiles"]
    RUNNER["robocopy2rust-runner<br/>Host Env, CREATE_NO_WINDOW Runner,<br/>Output Parser, CancelToken, SHA-256"]
    REPORT["robocopy2rust-report<br/>Air-gapped HTML / JSON / MD,<br/>Legacy Log Importer"]
    MCP["robocopy2rust-mcp<br/>JSON-RPC 2.0 stdio Server<br/>9 Tools + Safety Guard"]
    CLI["robocopy2rust-cli<br/>11 Subcommands + Dual GUI Launcher"]
    WIN32["robocopy2rust-win32<br/>Native WinSafe 0.0.29 GUI<br/>Windows Default"]
    ICED["robocopy2rust-iced<br/>Iced 0.14 Cross-Platform GUI<br/>Linux, macOS, Windows"]

    RUNNER --> CORE
    REPORT --> CORE
    REPORT --> RUNNER
    MCP --> CORE
    MCP --> RUNNER
    MCP --> REPORT
    CLI --> CORE
    CLI --> RUNNER
    CLI --> REPORT
    CLI --> MCP
    WIN32 --> CORE
    WIN32 --> RUNNER
    WIN32 --> REPORT
    ICED --> CORE
    ICED --> RUNNER
    ICED --> REPORT
Loading

Both GUIs (robocopy2rust-win32 and robocopy2rust-iced) share the exact same underlying engine (core + runner + report) and launch independently as lightweight OS-native processes via robocopy2rust-cli.


1. robocopy2rust-core

Foundational library crate (crates/robocopy2rust-core/src/) containing all zero-UI business logic:

Domain Schema (model.rs)

The canonical job model is RobocopyJob, organized into typed option groups:

  • CopyOptions (/S, /E, /LEV:n, /Z, /B, /ZB, /J, /EFSRAW, CopyFlags /COPY://SEC//COPYALL//NOCOPY, /SECFIX, /TIMFIX, /PURGE, /MIR, /MOV, /MOVE, FileAttrFlags /A+://A-:, /CREATE, /FAT, /256, /MON:n, /MOT:m, /RH:hhmm-hhmm, /PF, /IPG:n, /SJ, /SL, /MT[:n], DirCopyFlags /DCOPY://NODCOPY, /NOOFFLOAD, /COMPRESS, SparseMode /SPARSE[:Y|N], /NOCLONE).
  • ThrottleOptions (/IoMaxSize:n[KMG], /IoRate:n[KMG], /Threshold:n[KMG]).
  • FileSelectionOptions (/A, /M, /IA:, /XA:, /XF, /XD, /XC, /XN, /XO, /XX, /XL, /IS, /IT, /IM, /MAX:n, /MIN:n, /MAXAGE:, /MINAGE:, /MAXLAD:, /MINLAD:, /FFT, /DST, /XJ, /XJD, /XJF).
  • RetryOptions (/R:n, /W:n, /REG, /TBD, /LFSM[:n[KMG]]).
  • LoggingOptions (/L, /X, /V, /TS, /FP, /BYTES, /NS, /NC, /NFL, /NDL, /NP, /ETA, LogFileMode (/LOG:, /LOG+:, /UNILOG:, /UNILOG+:), /TEE, /NJH, /NJS, /UNICODE).
  • JobFileOptions (/JOB:, /SAVE:, /QUIT, /NOSD, /NODD).

Important Default Constructors:

  • RobocopyJob::default() applies safe interactive defaults: /E (include empty subdirectories), /MT:8, /R:3, /W:5 (preventing Robocopy's notorious 1,000,000-retry × 30-second stall), and /ETA.
  • RobocopyJob::empty_cli_defaults() starts clean matching native Robocopy defaults so imported command lines and .rcj files only emit switches explicitly present in the input.
  • Helper methods has_destructive_flags() (returns false when /L is active), destructive_switch_names(), and with_list_only() (enables /L /FP /BYTES while clearing /NFL / /NS / /NC for clear dry-run diffs).

Path Normalization & Windows Quoting (command.rs)

Microsoft robocopy.exe uses C runtime CommandLineToArgvW rules where a trailing \ immediately before a closing double quote escapes the quote ("C:\Data\" corrupts argv).

  • normalize_robocopy_path(path): Trims whitespace/quotes and strips trailing / or \ from non-root directories (C:\Users\Alice\ → C:\Users\Alice, \\server\share\ → \\server\share) while preserving drive roots (C:\, normalized from C:/) and \.
  • quote_windows_arg(arg): Wraps tokens containing spaces, tabs, quotes, or shell metacharacters (& | < > ^ ( ) ; , % !)—or ending with \—in double quotes and doubles trailing backslashes before quotes (C:\ → "C:\\", C:\My Docs\ → "C:\My Docs\\").
  • Ordered Argument Assembly (build_args): Emits source, destination, file_specs, copy flags, throttle flags, scalar selection flags, retry flags, logging flags, job-file flags, then multi-value /XF and /XD lists (placed after scalar switches so positional exclusions cannot capture switches), followed by extra_args.

Bidirectional Command & .rcj Parsers (parser.rs, rcj.rs)

  • tokenize_windows_cmdline & parse_command_line: Parses arbitrary robocopy ... strings (stripping leading robocopy / robocopy.exe) according to CommandLineToArgvW escaping rules. Handles /SD:, /DD:, legacy or Windows 10/11 switches, and preserves unrecognized tokens inside extra_args with parse warnings instead of dropping them.
  • parse_rcj & serialize_rcj: Supports UTF-8, UTF-8 with BOM, UTF-16LE with BOM (Windows /SAVE: native encoding), and UTF-16BE with BOM; parses /SD:, /DD:, /IF, /XF, /XD sections and strips inline :: comment markers without truncating quoted paths.

Validation, Exit Decoding, Presets & Persistence (validation.rs, exit_code.rs, presets.rs, profiles.rs, logging.rs)

  • Validation Engine: Evaluates 16 rules across Error, Warning, and Info severities (details in Validation Rules & Exit Codes).
  • Exit Code Decoder: Decodes bitmask codes (0..=7 success, >= 8 failure, < 0 cancelled/terminated).
  • Persistent Store (ProfileStore): Stores profiles.json and history.json under dirs::config_dir()/robocopy2rust (%APPDATA%\robocopy2rust on Windows) using atomic temporary-file writes (.json.tmp → rename) and capping run history at the 200 most recent runs.
  • Logging (init_logging): Uses tracing_subscriber writing strictly to stderr (or an explicit log file) so CLI JSON stdout and MCP stdio JSON-RPC channels are never corrupted.

2. robocopy2rust-runner

Process execution and real-time output parsing crate (crates/robocopy2rust-runner/src/):

  • Environment Probe (env.rs): find_robocopy_executable() checks C:\Windows\System32\robocopy.exe first on Windows (preventing PATH shadowing), then scans PATH; detect_environment() reports OS, availability, resolved path, and config directory.
  • Live Streaming Executor (runner.rs):
    • spawn_job_runner spawns a background OS worker thread streaming RunnerEvent variants (Started, LogLine, FileAction, Progress, Error, Summary, Finished) over std::sync::mpsc.
    • Sets CREATE_NO_WINDOW (0x0800_0000) on Windows so GUI/headless runs never flash transient console windows.
    • stream_lines reads raw bytes in 4 KB chunks and splits on both \r and \n (collapsing \r\n), delivering Robocopy's in-place xx.x% progress carriage returns immediately without waiting for file completion.
    • Computes a continuous SHA-256 digest (log_sha256) across all stdout/stderr log lines.
    • CancelToken stores an AtomicBool, child PID, and cross-platform killer closure (taskkill /PID <pid> /T /F with CREATE_NO_WINDOW on Windows; kill -TERM <pid> on Unix) to terminate child trees cleanly. Cancelled runs report exit code -1 and cancelled: true.
  • Stateful Output Parser (output_parser.rs): Classifies 15 FileActionKind variants (NewFile, Newer, Older, Changed, Same, ExtraFile, ExtraDir, NewDir, Tweaked, Modified, Lonely, Mismatch, Failed, DirEntry, Other), regex-matches ERROR <n> (...) and Waiting <n> seconds... Retrying lines, disambiguates header Files : *.* from summary Files : total copied ..., and parses [KMGTP] size suffixes plus Bytes/sec. / MegaBytes/min. throughput.

3. robocopy2rust-report, robocopy2rust-mcp, robocopy2rust-cli & GUIs

  • robocopy2rust-report: Emits self-contained offline HTML (inline CSS + JS filter + dark/light toggle), schema-versioned JSON (robocopy2rust.audit.v1), and Markdown reports, plus imports legacy UTF-8/UTF-16 Robocopy logs. See Reports, .rcj & Script Exports.
  • robocopy2rust-mcp: Exposes 9 JSON-RPC 2.0 tools over stdio (2024-11-05) with strict destructive safety checks. See MCP Server Guide.
  • robocopy2rust-cli: Exposes 11 subcommands plus argumentless GUI launching (robocopy2rust-win32 default on Windows; robocopy2rust-iced on Linux/macOS or via --iced). See CLI Reference.
  • robocopy2rust-win32 & robocopy2rust-iced: Twin pure-Rust desktop consoles covered in Dual-GUI Guide.

Clone this wiki locally